flow_chat 0.8.2 → 0.10.0

data/docs/testing.md

@@ -1,30 +1,23 @@
-# Testing Guide
+# Testing
 
-FlowChat provides comprehensive testing capabilities for both USSD and WhatsApp flows. This guide covers everything from unit testing individual flows to using the powerful built-in simulator for interactive testing.
+FlowChat gives you two ways to exercise a flow without a live gateway: a web simulator for manual, interactive testing during development, and the HTTP gateway for automated request tests.
 
-## Testing Approaches
+## The simulator
 
-FlowChat supports multiple testing strategies depending on your needs:
+The simulator is a web page that drives your flows the way a real platform would, so you can step through a conversation from the browser. It works the same regardless of which gateway a flow targets.
 
-| Approach | Best For | Setup Complexity | Real API Calls |
-|----------|----------|------------------|----------------|
-| **Unit Testing** | Individual flow logic | Low | No |
-| **Simulator Mode** | Integration testing, development | Medium | No |
-| **Skip Validation** | Staging environments | Medium | Yes |
-| **Full Integration** | Production-like testing | High | Yes |
+Enable it in two steps.
 
-## Quick Start: Interactive Simulator
-
-The fastest way to test your flows is with the built-in web simulator:
-
-### 1. Configure Simulator
+Set the simulator secret during boot:
 
 ```ruby
-# config/initializers/flowchat.rb
-FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_simulator"
+# config/initializers/flow_chat.rb
+FlowChat::Config.simulator_secret = Rails.application.credentials.flow_chat_simulator_secret
 ```
 
-### 2. Create Simulator Controller
+The secret gates access. The simulator controller signs a cookie with it, and the gateways only enter simulator mode when that cookie is valid, so the simulator stays off in any environment where the secret is unset.
+
+Mount a controller that includes the simulator module and lists the endpoints to test:
 
 ```ruby
 # app/controllers/simulator_controller.rb
@@ -39,437 +32,51 @@ class SimulatorController < ApplicationController
 
   def configurations
     {
-      ussd: {
-        name: "USSD Integration",
-        icon: "📱", 
+      ussd_main: {
+        name: "USSD",
         processor_type: "ussd",
         gateway: "nalo",
-        endpoint: "/ussd",
-        color: "#007bff"
+        endpoint: "/ussd"
       },
-      whatsapp: {
-        name: "WhatsApp Integration",
-        icon: "💬",
-        processor_type: "whatsapp", 
+      whatsapp_main: {
+        name: "WhatsApp",
+        processor_type: "whatsapp",
         gateway: "cloud_api",
-        endpoint: "/whatsapp/webhook",
-        color: "#25D366"
+        endpoint: "/whatsapp/webhook"
       }
     }
   end
-
-  def default_config_key
-    :whatsapp
-  end
-
-  def default_phone_number
-    "+1234567890"
-  end
-
-  def default_contact_name
-    "Test User"
-  end
 end
 ```
 
-### 3. Add Route
-
 ```ruby
 # config/routes.rb
-Rails.application.routes.draw do
-  get '/simulator' => 'simulator#index'
-  # ... your other routes
-end
-```
-
-### 4. Enable Simulator in Controllers
-
-```ruby
-# app/controllers/whatsapp_controller.rb
-class WhatsappController < ApplicationController
-  skip_forgery_protection
-
-  def webhook
-  enable_simulator = Rails.env.development? # enabled in development by default
-    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator:) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
-
-    processor.run WelcomeFlow, :main_page
-  end
-end
-```
-
-### 5. Test Your Flows
-
-Visit [http://localhost:3000/simulator](http://localhost:3000/simulator) and start testing! 
-
-**Simulator Features:**
-- 📱 **Visual Interface** - Phone-like display showing actual conversation
-- 🔄 **Platform Switching** - Toggle between USSD and WhatsApp modes  
-- 📊 **Request Logging** - See HTTP requests and responses in real-time
-- 🎯 **Interactive Testing** - Character counting, validation, session management
-- 🛠️ **Developer Tools** - Reset sessions, view connection status
-
-## Unit Testing
-
-Test individual flows in isolation:
-
-### Basic Flow Testing
-
-```ruby
-# test/flows/welcome_flow_test.rb
-require 'test_helper'
-
-class WelcomeFlowTest < ActiveSupport::TestCase
-  def setup
-    @context = FlowChat::Context.new
-    @context.session = FlowChat::Session::CacheSessionStore.new
-    @context.session.init_session("test_session")
-  end
-
-  test "welcome flow collects name and shows greeting" do
-    # Simulate user entering name
-    @context.input = "John Doe"
-    app = FlowChat::Ussd::App.new(@context)
-    
-    # Expect flow to terminate with greeting
-    error = assert_raises(FlowChat::Interrupt::Terminate) do
-      flow = WelcomeFlow.new(app)
-      flow.main_page
-    end
-    
-    assert_includes error.prompt, "Hello, John Doe"
-  end
-
-  test "flow handles validation errors" do
-    # Test with empty input
-    @context.input = ""
-    app = FlowChat::Ussd::App.new(@context)
-    
-    # Should prompt for input again
-    error = assert_raises(FlowChat::Interrupt::Input) do
-      flow = RegistrationFlow.new(app)
-      flow.collect_email
-    end
-    
-    assert_includes error.prompt, "Email is required"
-  end
-end
-```
-
-### Testing Complex Flows
-
-```ruby
-# test/flows/registration_flow_test.rb
-class RegistrationFlowTest < ActiveSupport::TestCase
-  test "complete registration flow" do
-    context = FlowChat::Context.new
-    context.session = FlowChat::Session::CacheSessionStore.new
-    context.session.init_session("test_session")
-    
-    # Step 1: Enter email
-    context.input = "john@example.com"
-    app = FlowChat::Ussd::App.new(context)
-    
-    assert_raises(FlowChat::Interrupt::Input) do
-      flow = RegistrationFlow.new(app)
-      flow.main_page
-    end
-    
-    # Verify email was stored
-    assert_equal "john@example.com", context.session.get(:email)
-    
-    # Step 2: Enter age
-    context.input = "25"
-    
-    assert_raises(FlowChat::Interrupt::Input) do
-      flow = RegistrationFlow.new(app)
-      flow.main_page  # Continue from where we left off
-    end
-    
-    # Step 3: Confirm
-    context.input = "yes"
-    
-    assert_raises(FlowChat::Interrupt::Terminate) do
-      flow = RegistrationFlow.new(app)
-      flow.main_page
-    end
-  end
-end
-```
-
-## Integration Testing
-
-### Environment Configuration
-
-Set up different testing modes per environment:
-
-```ruby
-# config/initializers/flowchat.rb
-case Rails.env
-when 'development'
-  # Use simulator for easy testing
-  FlowChat::Config.whatsapp.message_handling_mode = :simulator
-  FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_dev"
-  
-when 'test'
-  # Use simulator for automated tests
-  FlowChat::Config.whatsapp.message_handling_mode = :simulator
-  FlowChat::Config.simulator_secret = "test_secret_key"
-  
-when 'staging'
-  # Use inline mode with real WhatsApp API but skip validation for testing
-  FlowChat::Config.whatsapp.message_handling_mode = :inline
-  FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
-  
-when 'production'
-  # Use background jobs with full security
-  FlowChat::Config.whatsapp.message_handling_mode = :background
-  FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
-  # No simulator secret in production
-end
-```
-
-### Simulator Mode Testing
-
-Test webhook endpoints using simulator mode:
-
-```ruby
-# test/controllers/whatsapp_controller_test.rb
-class WhatsappControllerTest < ActionDispatch::IntegrationTest
-  test "processes whatsapp message in simulator mode" do
-    webhook_payload = {
-      entry: [{
-        changes: [{
-          value: {
-            messages: [{
-              from: "1234567890",
-              text: { body: "Hello" },
-              type: "text",
-              id: "msg_123",
-              timestamp: Time.now.to_i
-            }]
-          }
-        }]
-      }],
-      simulator_mode: true  # Enable simulator mode
-    }
-
-    # Generate valid simulator cookie
-    valid_cookie = generate_simulator_cookie
-    
-    post "/whatsapp/webhook",
-      params: webhook_payload,
-      cookies: { flowchat_simulator: valid_cookie }
-    
-    assert_response :success
-    
-    # In simulator mode, response contains message data
-    response_data = JSON.parse(response.body)
-    assert response_data.key?("text")
-    assert_includes response_data["text"], "What's your name?"
-  end
-
-  test "multi-step flow maintains state" do
-    valid_cookie = generate_simulator_cookie
-    
-    # Step 1: Start conversation
-    post_simulator_message("start", valid_cookie)
-    assert_response :success
-    
-    # Step 2: Enter name
-    post_simulator_message("John", valid_cookie)
-    assert_response :success
-    
-    response_data = JSON.parse(response.body)
-    assert_includes response_data["text"], "Hello John"
-  end
-
-  private
-
-  def generate_simulator_cookie(secret = "test_secret_key")
-    timestamp = Time.now.to_i
-    message = "simulator:#{timestamp}"
-    signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret, message)
-    "#{timestamp}:#{signature}"
-  end
-
-  def post_simulator_message(text, cookie)
-    webhook_payload = {
-      entry: [{
-        changes: [{
-          value: {
-            messages: [{
-              from: "1234567890",
-              text: { body: text },
-              type: "text",
-              id: "msg_#{rand(1000)}",
-              timestamp: Time.now.to_i
-            }]
-          }
-        }]
-      }],
-      simulator_mode: true
-    }
-
-    post "/whatsapp/webhook",
-      params: webhook_payload,
-      cookies: { flowchat_simulator: cookie }
-  end
-end
-```
-
-### Testing with Disabled Validation
-
-For staging environments where you want to test real endpoints:
-
-```ruby
-test "webhook with disabled validation" do
-  # Create config with validation disabled
-  config = FlowChat::Whatsapp::Configuration.new(:test_config)
-  config.access_token = "test_token"
-  config.phone_number_id = "test_phone_id"
-  config.verify_token = "test_verify"
-  config.skip_signature_validation = true  # Disable validation for testing
-
-  webhook_payload = {
-    entry: [{
-      changes: [{
-        value: {
-          messages: [{
-            from: "1234567890",
-            text: { body: "Hello" },
-            type: "text"
-          }]
-        }
-      }]
-    }]
-  }
-
-  post "/whatsapp/webhook",
-    params: webhook_payload.to_json,
-    headers: { "Content-Type" => "application/json" }
-  
-  assert_response :success
-end
-```
-
-## Advanced Testing Scenarios
-
-### Testing Error Handling
-
-```ruby
-test "handles validation errors gracefully" do
-  valid_cookie = generate_simulator_cookie
-  
-  # Send invalid email
-  post_simulator_message("invalid-email", valid_cookie)
-  
-  response_data = JSON.parse(response.body)
-  assert_includes response_data["text"], "Invalid email format"
-  
-  # Send valid email - should proceed
-  post_simulator_message("john@example.com", valid_cookie)
-  
-  response_data = JSON.parse(response.body)
-  refute_includes response_data["text"], "Invalid email"
-end
+get "/simulator", to: "simulator#index"
 ```
 
-### Testing Media Responses
+Each entry in `configurations` points at one of your real webhook endpoints, so the simulator posts to the same controller actions the platform would. Open `/simulator`, pick an endpoint, and send messages.
 
-```ruby
-test "media responses in simulator mode" do
-  valid_cookie = generate_simulator_cookie
-  
-  post_simulator_message("help", valid_cookie)
-  
-  response_data = JSON.parse(response.body)
-  
-  # Check media is included
-  assert response_data.key?("media")
-  assert_equal "image", response_data["media"]["type"]
-  assert response_data["media"]["url"].present?
-end
-```
+## Automated tests
 
-### Testing Session Persistence
+For request specs, drive a flow through the HTTP gateway (`FlowChat::Http::Gateway::Simple`), which speaks plain JSON. Point a controller at your flow:
 
 ```ruby
-test "session data persists across requests" do
-  valid_cookie = generate_simulator_cookie
-  
-  # First request - enter name
-  post_simulator_message("John", valid_cookie)
-  
-  # Second request - session should remember name
-  post_simulator_message("continue", valid_cookie)
-  
-  response_data = JSON.parse(response.body)
-  assert_includes response_data["text"], "John"  # Name should be remembered
-end
-```
-
-## Performance Testing
-
-### Load Testing Background Jobs
-
-```ruby
-test "handles high message volume with background jobs" do
-  # Switch to background mode for this test
-  original_mode = FlowChat::Config.whatsapp.message_handling_mode
-  FlowChat::Config.whatsapp.message_handling_mode = :background
-  
-  messages = 10.times.map do |i|
-    create_whatsapp_message_payload("user#{i}")
-  end
-  
-  assert_enqueued_jobs 10 do
-    messages.each do |msg|
-      post "/whatsapp/webhook", params: msg
+class ChatController < ApplicationController
+  def webhook
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Http::Gateway::Simple
+      config.use_session_store FlowChat::Session::CacheSessionStore
     end
+    processor.run RegistrationFlow, :main_page
   end
-ensure
-  FlowChat::Config.whatsapp.message_handling_mode = original_mode
 end
 ```
 
-## Debugging Tests
+The Simple gateway expects `session_id` and `user_id` in the request and returns JSON with the prompt, choices, and any media. Post the next input with the same `session_id` to advance the conversation, and assert on the returned message and choices. Set `FlowChat::Config.cache` to a real store (for example `ActiveSupport::Cache::MemoryStore.new`) in your test setup so sessions persist across the requests in a single test.
 
-### Enable Debug Logging
+Because one flow behaves the same across platforms, a flow verified through the HTTP gateway behaves the same on USSD, WhatsApp, and Telegram, apart from each platform's rendering.
 
-```ruby
-# config/environments/test.rb
-config.log_level = :debug
+## Related
 
-# In tests
-Rails.logger.debug "Current session data: #{context.session.data}"
-```
-
-### Inspect Flow State
-
-```ruby
-test "debug flow execution" do
-  context = FlowChat::Context.new
-  context.session = FlowChat::Session::CacheSessionStore.new
-  context.session.init_session("debug_session")
-  
-  # Add debugging
-  context.input = "test@example.com"
-  app = FlowChat::Ussd::App.new(context)
-  
-  flow = RegistrationFlow.new(app)
-  
-  # Inspect state before execution
-  puts "Session before: #{context.session.data}"
-  
-  begin
-    flow.main_page
-  rescue FlowChat::Interrupt::Input => e
-    puts "Flow interrupted with: #{e.prompt}"
-    puts "Session after: #{context.session.data}"
-  end
-end
-```
+- [Getting started](getting-started.md)
+- [Configuration](configuration.md)

data/examples/custom_session_id_example.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+# Example: Custom Session ID Configuration with Proc
+#
+# This example demonstrates how to use a custom proc for session ID generation
+# in FlowChat applications. The proc allows complete customization of how
+# session IDs are generated based on context data.
+
+require "flow_chat"
+
+class CustomSessionIdController < ApplicationController
+  def ussd_endpoint
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Ussd::Gateway::Nalo
+      config.use_session_store FlowChat::Session::CacheSessionStore
+
+      # Example 1: Custom session ID using block/proc
+      config.use_session_config do |context|
+        # Create a custom session ID based on your business logic
+        user_phone = context["request.msisdn"]
+        flow_name = context["flow.name"]
+        gateway = context["request.gateway"]
+        timestamp = Time.current.strftime("%Y%m%d")
+
+        # Custom format: flow_gateway_date_hashedphone
+        "#{flow_name}_#{gateway}_#{timestamp}_#{hash_phone(user_phone)}"
+      end
+    end
+
+    processor.run(SurveyFlow, :main_menu)
+  end
+
+  def whatsapp_endpoint
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+
+      # Example 2: Multi-tenant session IDs
+      config.use_session_config do |context|
+        tenant_id = extract_tenant_from_request(context)
+        user_id = context["request.user_id"] || context["request.msisdn"]
+        flow_name = context["flow.name"]
+
+        "tenant_#{tenant_id}_flow_#{flow_name}_user_#{hash_identifier(user_id)}"
+      end
+    end
+
+    processor.run(CustomerSupportFlow, :handle_inquiry)
+  end
+
+  def http_endpoint
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Http::Gateway::Simple
+      config.use_session_store FlowChat::Session::CacheSessionStore
+
+      # Example 3: API session with custom expiration tracking
+      config.use_session_config do |context|
+        api_key = context.controller.request.headers["X-API-Key"]
+        request_id = context["request.id"]
+
+        # Include API key hash for session isolation per API client
+        "api_#{hash_identifier(api_key)}_req_#{request_id}"
+      end
+    end
+
+    processor.run(ApiFlow, :handle_request)
+  end
+
+  private
+
+  def hash_phone(phone)
+    require "digest"
+    Digest::SHA256.hexdigest(phone)[0, 8]
+  end
+
+  def hash_identifier(identifier)
+    require "digest"
+    Digest::SHA256.hexdigest(identifier.to_s)[0, 8]
+  end
+
+  def extract_tenant_from_request(context)
+    # Extract tenant from subdomain or header
+    request = context.controller&.request
+    return "default" unless request
+
+    host = request.host
+    subdomain = host.split(".").first
+    subdomain if subdomain != "www"
+  end
+end
+
+# Example flows for demonstration
+class SurveyFlow < FlowChat::Flow
+  def main_menu
+    app.screen(:menu) { |p| p.ask "Welcome! Choose an option:", choices: ["Survey", "Exit"] }
+  end
+end
+
+class CustomerSupportFlow < FlowChat::Flow
+  def handle_inquiry
+    app.screen(:inquiry) { |p| p.ask "How can we help you today?" }
+  end
+end
+
+class ApiFlow < FlowChat::Flow
+  def handle_request
+    app.screen(:request) { |p| p.ask "API request received. Provide data:" }
+  end
+end
+
+# Note: The custom session ID proc approach provides:
+# - Complete control over session ID format
+# - Access to full context (request data, flow info, etc.)
+# - Ability to implement complex business logic
+# - Support for multi-tenancy, API authentication, etc.
+#
+# The proc should return a string that will be used as the session ID.
+# Make sure the returned ID is unique for your use case to avoid
+# session collisions.