flow_chat 0.8.2 → 0.9.0

data/README.md

@@ -6,64 +6,80 @@
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.3.0-red.svg)](https://www.ruby-lang.org/)
 [![Rails](https://img.shields.io/badge/rails-%3E%3D%206.0-red.svg)](https://rubyonrails.org/)
 
-FlowChat is a Rails framework for building sophisticated conversational workflows for USSD and WhatsApp messaging. Define multi-step conversations as Ruby classes with automatic session management, input validation, and cross-platform compatibility.
+FlowChat is a powerful Rails framework for building sophisticated conversational interfaces across **multiple platforms** with a **pluggable gateway architecture**. Create interactive flows with menus, prompts, validation, media support, and session management using a unified, intuitive API that works across USSD, WhatsApp, Telegram, HTTP, and any custom platforms you build.
 
-## Key Features
+## ✨ Key Features
 
-- 🎯 **Declarative Flow Definition** - Define conversations as Ruby classes
-- 🔄 **Automatic Session Management** - Persistent state across requests  
-- ✅ **Input Validation & Transformation** - Built-in validation and data conversion
-- 📱 **USSD & WhatsApp Support** - Single codebase, multiple platforms
-- 💬 **Rich WhatsApp Features** - Interactive buttons, lists, media support
-- 🔧 **Standalone WhatsApp Client** - Send messages outside of flows
-- 📊 **Built-in Instrumentation** - Monitoring and metrics out of the box
-- 🧪 **Testing Tools** - Built-in simulator for development and testing
+- **🔄 Unified API**: Single codebase that works across all platforms
+- **🔌 Pluggable Gateways**: Extensible architecture supporting multiple backends per platform
+- **📱 Multi-Platform**: Out of the box support for USSD, WhatsApp, Telegram, HTTP, and more, with simulator for testing
+- **🎯 Screen-Based Navigation**: Intuitive screen() method for building conversational flows
+- **💾 Advanced Session Management**: Flexible session boundaries and storage options
+- **🔧 Middleware Architecture**: Extensible middleware system for custom processing
+- **🎨 Rich Prompts**: Support for text, media, selections, yes/no prompts, validation, and transformations
+- **📊 Built-in Instrumentation**: Comprehensive logging and metrics collection
+- **🧪 Testing Support**: Built-in simulator for development and testing
+- **🏢 Multi-Tenancy**: In-built support for custom configuration per tenant and URL-based isolation
+- **🚀 Background Processing**: Job queue support for WhatsApp messaging
 
-## Installation
+## 🚀 Quick Start
 
-Add to your Gemfile:
+### Installation
+
+Add FlowChat to your Rails application:
 
 ```ruby
+# Gemfile
 gem 'flow_chat'
 ```
 
-Then run:
-
 ```bash
 bundle install
 ```
 
-## Quick Start
-
-### USSD Example
-
-Create a flow in `app/flow_chat/welcome_flow.rb`:
+### Define your flow
 
 ```ruby
+# app/flow_chat/welcome_flow.rb
+
 class WelcomeFlow < FlowChat::Flow
   def main_page
     name = app.screen(:name) do |prompt|
-      prompt.ask "What's your name?",
+      prompt.ask "Welcome! What's your name?",
         transform: ->(input) { input.strip.titleize }
     end
 
-    language = app.screen(:language) do |prompt|
-      prompt.select "Choose language:", ["English", "French", "Spanish"]
+    choice = app.screen(:main_menu) do |prompt|
+      prompt.select "Hi #{name}! Choose:", {
+        "1" => "Account Info",
+        "2" => "Make Payment",
+        "3" => "Support"
+      }
     end
 
-    app.say "Hello #{name}! Language set to #{language}."
+    case choice
+    when "1"
+      show_account_info
+    when "2"
+      make_payment  
+    when "3"
+      app.say "Call us: 123-456-7890"
+    end
   end
+
+  # ... implement your flow methods
 end
 ```
 
-Create a controller:
+### Basic USSD Application
 
 ```ruby
+# app/controllers/ussd_controller.rb
 class UssdController < ApplicationController
   skip_forgery_protection
 
   def process_request
-    processor = FlowChat::Ussd::Processor.new(self) do |config|
+    processor = FlowChat::Processor.new(self) do |config|
       config.use_gateway FlowChat::Ussd::Gateway::Nalo
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
@@ -73,33 +89,34 @@ class UssdController < ApplicationController
 end
 ```
 
-Add route in `config/routes.rb`:
+### Basic WhatsApp Application
 
 ```ruby
-  post 'ussd' => 'ussd#process_request'
-```
-
-### WhatsApp Example
+# app/controllers/whatsapp_controller.rb
+class WhatsappController < ApplicationController
+  skip_forgery_protection
 
-Configure credentials in `config/credentials.yml.enc`:
+  def webhook
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
 
-```yaml
-whatsapp:
-  access_token: "your_access_token"
-  phone_number_id: "your_phone_number_id"
-  verify_token: "your_verify_token"
-  app_secret: "your_app_secret"
+    processor.run WelcomeFlow, :main_page
+  end
+end
 ```
 
-Create a controller:
+### Basic Telegram Application
 
 ```ruby
-class WhatsappController < ApplicationController
+# app/controllers/telegram_controller.rb
+class TelegramController < ApplicationController
   skip_forgery_protection
 
   def webhook
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Telegram::Gateway::BotApi
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
 
@@ -108,102 +125,270 @@ class WhatsappController < ApplicationController
 end
 ```
 
-Add route:
+### Basic HTTP API Application
 
 ```ruby
-  match '/whatsapp/webhook', to: 'whatsapp#webhook', via: [:get, :post]
+# app/controllers/api_controller.rb
+class ApiController < ApplicationController
+  def chat
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Http::Gateway::Simple
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
 ```
+> Same WelcomeFlow works across ALL platforms!
+
 
-## Core Concepts
+## 🏗️ Architecture
+
+FlowChat uses a **composition-based architecture** with these core components:
+
+- **Processor**: Orchestrates request processing through middleware stack
+- **Gateway**: Platform-specific request/response handling (Nalo, WhatsApp Cloud API)
+- **App**: Unified application interface with screen-based navigation
+- **Session**: Flexible session management with configurable boundaries
+- **Middleware**: Extensible processing pipeline
+
+```
+┌─────────────┐    ┌──────────────┐    ┌─────────────┐
+│   Gateway   │ -> │ Session      │ -> │ Custom      │
+│             │    │ Middleware   │    │ Middleware  │
+└─────────────┘    └──────────────┘    └─────────────┘
+                                              │
+                                              v
+┌─────────────┐    ┌──────────────┐    ┌─────────────┐
+│ Flow/Action │ <- │   Executor   │ <- │     App     │
+│             │    │              │    │             │
+└─────────────┘    └──────────────┘    └─────────────┘
+```
 
-### Flows and Screens
+## 🔌 Pluggable Gateway Architecture
 
-**Flows** define conversation logic. **Screens** collect user input with automatic validation:
+FlowChat's power comes from its pluggable gateway system. Each platform can have multiple gateway implementations:
 
 ```ruby
-class RegistrationFlow < FlowChat::Flow
-  def main_page
-email = app.screen(:email) do |prompt|
-      prompt.ask "Enter email:",
-        validate: ->(input) { "Invalid email" unless input.include?("@") },
-        transform: ->(input) { input.downcase.strip }
-    end
+# Create your own SMS gateway
+class MyCompany::Sms::Gateway::Twilio
+  def initialize(app, config)
+    @app = app
+    @config = config
+  end
+
+  def call(context)
+    # Parse Twilio webhook, set context values
+    context["request.msisdn"] = params["From"]
+    context["request.platform"] = :sms
+    context.input = params["Body"]
+    
+    # Process through middleware
+    type, prompt, choices, media = @app.call(context)
+    
+    # Send response via Twilio API
+    send_sms_response(prompt, to: context["request.msisdn"])
+  end
 
-confirmed = app.screen(:confirm) do |prompt|
-      prompt.yes? "Create account for #{email}?"
+  # Optional: Configure platform-specific middleware
+  def self.configure_middleware_stack(builder, custom_middleware)
+    builder.use MyCompany::Sms::MessageTransformMiddleware
+    builder.use custom_middleware
+  end
+end
+
+# Use your custom gateway
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_gateway MyCompany::Sms::Gateway::Twilio, sms_config
 end
+```
+
+## 📚 Documentation
 
-if confirmed
-      create_account(email)
-      app.say "Account created successfully!"
-    else
-      app.say "Registration cancelled."
+### Getting Started
+- [**Getting Started Guide**](docs/getting-started.md) - Comprehensive setup and first app
+- [**Architecture Overview**](docs/architecture.md) - Deep dive into FlowChat's design
+- [**Configuration**](docs/configuration.md) - Complete configuration reference
+
+### Platform Guides
+- [**USSD Development**](docs/platforms/ussd.md) - USSD-specific features and examples
+- [**WhatsApp Development**](docs/platforms/whatsapp.md) - WhatsApp Business API integration
+- [**Telegram Development**](docs/platforms/telegram.md) - Telegram Bot API integration
+- [**HTTP Development**](docs/platforms/http.md) 🚧 - API endpoints and webhooks
+- [**Multi-Platform Apps**](docs/platforms/multi-platform.md) 🚧 - Building unified experiences
+
+### Advanced Topics
+- [**Gateway Development**](docs/gateway-development.md) - Creating custom gateways and platforms
+- [**Session Management**](docs/session-management.md) 🚧 - Session boundaries and storage
+- [**Middleware Development**](docs/middleware.md) 🚧 - Creating custom middleware
+- [**Testing & Simulation**](docs/testing.md) - Testing strategies and simulator usage
+- [**Background Jobs**](docs/background-jobs.md) 🚧 - Async processing for WhatsApp
+- [**Instrumentation**](docs/instrumentation.md) - Monitoring, logging, and error tracking
+
+### API Reference
+- [**Core API**](docs/api-reference/core.md) 🚧 - Processor, App, Flow classes
+- [**Prompts & Validation**](docs/api-reference/prompts.md) 🚧 - Interactive prompts and validation
+- [**Gateways**](docs/api-reference/gateways.md) 🚧 - Platform gateway interfaces
+- [**Session Stores**](docs/api-reference/session-stores.md) 🚧 - Session storage options
+
+## 🎯 Core Concepts
+
+### Screen-Based Navigation
+
+Build conversational flows using the intuitive `screen()` method:
+
+```ruby
+def registration_flow
+  # Each screen automatically handles state and navigation
+  email = app.screen(:email) do |prompt|
+    prompt.ask "Enter your email:",
+      validate: ->(input) { 
+        "Invalid email" unless input.include?("@")
+      }
+  end
+
+  name = app.screen(:name) do |prompt|
+    prompt.ask "Enter your full name:",
+      transform: ->(input) { input.strip.titleize }
+  end
+
+  # Confirmation screen with rich prompts
+  confirmed = app.screen(:confirm) do |prompt|
+    prompt.yes? "Confirm registration for #{name} (#{email})?"
+  end
+
+  if confirmed
+    create_user(name, email)
+    app.say "Welcome #{name}! Registration complete."
+  else
+    app.say "Registration cancelled."
+  end
+end
+```
+
+### Multi-Platform Compatibility
+
+Write once, run everywhere:
+
+```ruby
+class MenuFlow < FlowChat::Flow
+  def main_menu
+    choice = app.screen(:menu) do |prompt|
+      prompt.select "Choose an option:", {
+        "info" => "📋 Information",      # Rich for WhatsApp
+        "help" => "❓ Help",             # Falls back to text for USSD  
+        "exit" => "👋 Exit"
+      }
     end
+    
+    # Same logic works on both platforms
+    handle_choice(choice)
   end
 end
 ```
 
-### Input Methods
+### Flexible Session Management
 
-- **`prompt.ask()`** - Free-form input with optional validation
-- **`prompt.select()`** - Force selection from predefined options  
-- **`prompt.yes?()`** - Simple yes/no questions
+Configure sessions for your use case:
 
-## WhatsApp Client
+```ruby
+# Durable sessions across timeouts
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_durable_sessions  # Uses user identifier (usually phone number) for session ID
+end
+
+# Cross-platform sessions
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_cross_platform_sessions  # Share sessions between platforms (e.g. USSD & WhatsApp)
+end
+
+# URL-based multi-tenancy
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_url_isolation  # tenant1.app.com vs tenant2.app.com
+end
+```
+
+## 🛠️ Supported Platforms & Gateways
+
+| Platform | Available Gateways | Features |
+|----------|-------------------|----------|
+| **USSD** | `Nalo` ✅, Custom | Pagination, choice mapping, session management |
+| **WhatsApp** | `CloudApi` ✅, Custom | Rich media, buttons, lists, templates, background jobs |
+| **Telegram** | `BotApi` ✅, Custom | Inline keyboards, rich media, callbacks, group chats |
+| **HTTP** | `Simple` ✅, Custom | Testing, webhooks, API endpoints, JSON responses |
+| **Simulator** | Built-in ✅ | Development testing, conversation replay, flow debugging |
+| **Custom** | *Your Gateway* | Implement any platform by creating a gateway class |
+
+*✅ = Included with FlowChat*
 
-Send messages outside of flows:
+### Gateway Examples
 
 ```ruby
-config = FlowChat::Whatsapp::Configuration.from_credentials
-client = FlowChat::Whatsapp::Client.new(config)
-
-# Send messages
-client.send_text("+1234567890", "Hello!")
-client.send_buttons("+1234567890", "Choose:", [
-  { id: 'option1', title: 'Option 1' },
-  { id: 'option2', title: 'Option 2' }
-])
+# Built-in gateways (included with FlowChat)
+config.use_gateway FlowChat::Ussd::Gateway::Nalo
+config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, whatsapp_config
+config.use_gateway FlowChat::Telegram::Gateway::BotApi, telegram_config
+config.use_gateway FlowChat::Http::Gateway::Simple
+
+# Custom gateway examples (you would build these)
+config.use_gateway MyCompany::Sms::Gateway::Twilio, twilio_config
+config.use_gateway MyCompany::Slack::Gateway::BoltJS, slack_config
+```
+
+## 📦 Example Applications
+
+- [**USSD Banking App**](docs/examples/ussd-banking.md) 🚧 - Complete banking flow with validation
+- [**WhatsApp Customer Service**](docs/examples/whatsapp-support.md) 🚧 - Media support and templates  
+- [**HTTP API Chatbot**](docs/examples/http-api.md) 🚧 - JSON API for web/mobile integration
+- [**Multi-Platform E-commerce**](docs/examples/multi-platform-shop.md) 🚧 - Unified shopping across USSD, WhatsApp, and HTTP
+- [**Multi-Tenant SaaS**](docs/examples/multi-tenant.md) 🚧 - URL-based tenant isolation
+- [**Custom Gateway Example**](docs/examples/custom-gateway.md) 🚧 - Building a Telegram gateway
+
+## 🧪 Testing & Development
+
+FlowChat includes a built-in simulator interface for easy development and testing:
+
+```ruby
+# Simulator is automatically enabled in development
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo  # or any gateway
+end
+
+# Explicitly control simulator mode if needed
+processor = FlowChat::Processor.new(self, enable_simulator: false) do |config|
+  # Disable simulator even in development
+end
 ```
 
-## Testing Simulator
+The simulator provides a web interface for testing your flows during development. It works the same regardless of which gateway you're using, allowing you to test your conversational logic before deploying to actual platforms.
 
-FlowChat includes a powerful built-in simulator with a modern web interface for testing both USSD and WhatsApp flows:
+**Learn more**: [Testing & Simulation Guide](docs/testing.md)
 
-![FlowChat Simulator](docs/images/simulator.png)
+## 🤝 Contributing
 
-Features:
-- 📱 **Visual Interface** - Phone-like display with real conversation flow
-- 🔄 **Environment Switching** - Toggle between USSD and WhatsApp modes
-- 📊 **Request Logging** - Real-time HTTP request/response monitoring
-- 🎯 **Interactive Testing** - Test flows with character counting and validation
-- 🛠️ **Developer Tools** - Session management and connection status
+We welcome contributions!
 
-See the [Testing Guide](docs/testing.md) for complete setup instructions and testing strategies.
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
+## 📄 License
 
-## Documentation
+FlowChat is released under the [MIT License](LICENSE.txt).
 
-- **[WhatsApp Setup](docs/whatsapp-setup.md)** - Comprehensive WhatsApp configuration
-- **[USSD Setup](docs/ussd-setup.md)** - USSD gateway configuration and examples
-- **[Flow Development](docs/flows.md)** - Advanced flow patterns and techniques
-- **[Session Management](docs/sessions.md)** - Session architecture and configuration
-- **[Media Support](docs/media.md)** - Rich media handling for WhatsApp
-- **[Testing Guide](docs/testing.md)** - Complete testing strategies
-- **[Configuration Reference](docs/configuration.md)** - All configuration options
-- **[Instrumentation](docs/instrumentation.md)** - Monitoring and metrics
-- **[Security](docs/security.md)** - Security best practices
-- **[Examples](examples/)** - Complete working examples
+## 🆘 Support
 
-## Examples
+- **Documentation**: Comprehensive guides in the [docs/](docs/) directory
+- **Issues**: [GitHub Issues](https://github.com/radioactive-labs/flow_chat/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/radioactive-labs/flow_chat/discussions)
 
-See the [examples directory](examples/) for complete implementations:
+## 🏢 Commercial Support
 
-- **[USSD Controller](examples/ussd_controller.rb)** - Full USSD implementation
-- **[WhatsApp Controller](examples/whatsapp_controller.rb)** - Basic WhatsApp setup
-- **[Multi-tenant WhatsApp](examples/multi_tenant_whatsapp_controller.rb)** - Advanced WhatsApp
-- **[Background Jobs](examples/whatsapp_message_job.rb)** - Async message processing
-- **[Simulator Controller](examples/simulator_controller.rb)** - Testing setup
+FlowChat is developed by [Radioactive Labs](https://github.com/radioactive-labs). Commercial support, custom development, and consulting services are available.
 
-## License
+---
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+**Ready to build amazing conversational experiences?** Check out the [Getting Started Guide](docs/getting-started.md) to create your first FlowChat application.

data/Rakefile

@@ -1,5 +1,9 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "standard/rake"
+
+# Load custom rake tasks
+Dir.glob("lib/tasks/**/*.rake").each { |r| load r }
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
@@ -7,4 +11,4 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
-task default: :test
+task default: %i[test standard]