flow_chat 0.9.0 → 0.10.0

data/docs/testing.md

@@ -1,29 +1,23 @@
-# Testing & Simulation
+# Testing
 
-FlowChat provides a sophisticated web-based simulator for testing conversational flows across multiple platforms (USSD, WhatsApp, HTTP) without requiring actual gateway integrations.
+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.
 
-## Built-in Web Simulator
+## The simulator
 
-### Overview
+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.
 
-The FlowChat simulator is a browser-based testing interface that provides:
+Enable it in two steps.
 
-- **Multi-Platform Testing**: USSD, WhatsApp, and HTTP with platform-specific UI
-- **Real-Time Request Logging**: Complete HTTP traffic monitoring and debugging
-- **Security**: HMAC-signed cookie authentication
-- **Platform-Specific Rendering**: Accurate simulation of each platform's behavior
-- **Configuration Management**: Test multiple endpoints from a single interface
-
-### Setup & Configuration
-
-#### 1. Basic Configuration
+Set the simulator secret during boot:
 
 ```ruby
 # config/initializers/flow_chat.rb
-FlowChat::Config.simulator_secret = "your_secure_secret_key_here"
+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
@@ -36,318 +30,53 @@ class SimulatorController < ApplicationController
 
   protected
 
-  # Configure available test endpoints
   def configurations
     {
       ussd_main: {
-        name: "USSD (Nalo)",
-        description: "USSD integration using Nalo gateway",
+        name: "USSD",
         processor_type: "ussd",
         gateway: "nalo",
-        endpoint: "/ussd",
-        icon: "📱",
-        color: "#28a745",
-        settings: {
-          phone_number: default_phone_number,
-          session_timeout: 300
-        }
+        endpoint: "/ussd"
       },
       whatsapp_main: {
-        name: "WhatsApp (Cloud API)",
-        description: "WhatsApp integration using Cloud API",
+        name: "WhatsApp",
         processor_type: "whatsapp",
-        gateway: "cloud_api", 
-        endpoint: "/whatsapp/webhook",
-        icon: "💬",
-        color: "#25D366",
-        settings: {
-          phone_number: default_phone_number,
-          contact_name: default_contact_name
-        }
-      },
-      http_api: {
-        name: "HTTP API",
-        description: "JSON HTTP API endpoint",
-        processor_type: "http",
-        gateway: "http_simple",
-        endpoint: "/http/webhook", 
-        icon: "🌐",
-        color: "#0066cc",
-        settings: {
-          user_id: default_phone_number
-        }
+        gateway: "cloud_api",
+        endpoint: "/whatsapp/webhook"
       }
     }
   end
-
-  def default_phone_number
-    "+233244123456"
-  end
-
-  def default_contact_name
-    "John Doe"
-  end
-
-  def default_config_key
-    :ussd_main
-  end
 end
 ```
 
-#### 3. Add Route
-
 ```ruby
 # config/routes.rb
-Rails.application.routes.draw do
-  get '/simulator' => 'simulator#index'
-  # ... other routes
-end
+get "/simulator", to: "simulator#index"
 ```
 
-### Security Features
-
-#### HMAC-Signed Cookies
-
-The simulator uses secure, timestamped cookies for authentication:
-
-```ruby
-# Automatic cookie generation in simulator controller
-def set_simulator_cookie
-  simulator_secret = FlowChat::Config.simulator_secret
-  timestamp = Time.now.to_i
-  message = "simulator:#{timestamp}"
-  signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), simulator_secret, message)
-  
-  cookies[:flowchat_simulator] = {
-    value: "#{timestamp}:#{signature}",
-    expires: 24.hours.from_now,
-    secure: request.ssl?,  # HTTPS only in production
-    httponly: true,        # Prevent XSS
-    same_site: :lax       # CSRF protection
-  }
-end
-```
+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.
 
-#### Automatic Enablement
+## Automated tests
 
-Simulator mode is automatically enabled when:
+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
-# In processor initialization
-enable_simulator: Rails.env.local?  # true for development/test
-```
-
-### Platform-Specific Features
-
-#### USSD Testing
-
-**Interface**: Menu-style display with character limits and pagination
-
-**Features**:
-- Network-specific character limits (MTN: 160, Airtel: 140, etc.)
-- Session timeout simulation
-- Menu option selection
-- Automatic pagination for long content
-
-**Request Format**:
-```ruby
-{
-  msisdn: "+233244123456",
-  text: "user_input", 
-  session_id: "session_123",
-  network: "mtn"
-}
-```
-
-#### WhatsApp Testing
-
-**Interface**: Chat-style interface with contact avatars and message history
-
-**Features**:
-- Contact name and avatar display
-- Interactive buttons and lists
-- Media support (images, documents, audio, video)
-- Cloud API webhook simulation
-
-**Request Format**:
-```javascript
-{
-  simulator_mode: true,
-  entry: [{
-    changes: [{
-      value: {
-        messaging_product: "whatsapp",
-        metadata: {
-          display_phone_number: "233244123456",
-          phone_number_id: "phone_number_id_123"
-        },
-        messages: [{
-          text: { body: "user_input" },
-          type: 'text'
-        }],
-        contacts: [{
-          profile: { name: "John Doe" },
-          wa_id: "233244123456"
-        }]
-      }
-    }]
-  }]
-}
-```
-
-**Response Handling**:
-```javascript
-// Simulator expects JSON response for full simulation
-{
-  mode: "simulator",
-  webhook_processed: true,
-  would_send: {
-    to: "233244123456",
-    type: "text",
-    text: { body: "Response message" }
-  },
-  message_info: {
-    to: "233244123456",
-    contact_name: "John Doe",
-    timestamp: "2024-01-01T12:00:00Z"
-  }
-}
-```
-
-#### HTTP Testing
-
-**Interface**: API-style interface showing JSON request/response
-
-**Features**:
-- JSON payload display
-- Session management
-- Custom headers
-- Error handling
-
-**Request Format**:
-```javascript
-{
-  session_id: "session_123",
-  user_id: "+233244123456",
-  input: "user_input",
-  simulator_mode: true
-}
-```
-
-### Request Logging & Debugging
-
-#### Real-Time Traffic Monitoring
-
-The simulator provides comprehensive request logging:
-
-```javascript
-// Automatic logging of all HTTP traffic
-addRequestLog('POST', endpoint, requestData, responseData, statusCode, errorMessage)
-```
-
-**Log Information**:
-- Request method and URL
-- Complete request payload
-- Response status and data
-- Timestamps and duration
-- Error messages with helpful debugging hints
-
-#### Error Handling
-
-The simulator provides detailed error messages for common issues:
-
-- **Connection Failures**: CORS, SSL, network issues
-- **404 Not Found**: Route configuration problems  
-- **500 Server Errors**: Application errors
-- **Authentication Issues**: Invalid simulator cookies
-
-### Enabling Simulator Mode in Your Endpoints
-
-#### For WhatsApp Endpoints
-
-Your WhatsApp processor automatically handles simulator mode:
-
-```ruby
-class WhatsappController < ApplicationController
-  def webhook
-    processor = FlowCha::Processor.new(self, enable_simulator: !Rails.env.production?) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
-
-    processor.run WelcomeFlow, :main_page
-  end
-end
-```
-
-#### For HTTP Endpoints
-
-HTTP endpoints work automatically with the simulator:
-
-```ruby
-class HttpController < ApplicationController  
+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 WelcomeFlow, :main_page
+    processor.run RegistrationFlow, :main_page
   end
 end
 ```
 
-### Usage Workflow
-
-#### 1. Start the Simulator
-
-```bash
-rails server
-# Visit http://localhost:3000/simulator
-```
-
-#### 2. Configure Test Environment
-
-- Select endpoint from configuration dropdown
-- Set phone number and contact name
-- Choose platform type (USSD/WhatsApp/HTTP)
-
-#### 3. Test Conversation Flows
-
-- Click "Start Session" to begin
-- Send messages through the platform-specific interface
-- Monitor request/response logs in real-time
-- Reset session to test different scenarios
-
-#### 4. Debug Issues
-
-- Check request logs for HTTP traffic details
-- Verify endpoint responses and status codes
-- Review error messages for configuration issues
-- Test different platforms and configurations
-
-### Best Practices
-
-#### Security
-
-- Always set `FlowChat::Config.simulator_secret` in production
-- Use secure cookies over HTTPS in production
-- Restrict simulator access to development/staging environments
-
-#### Testing Strategy
-
-1. **Start with Simulator**: Test flows before gateway integration
-2. **Test All Platforms**: Verify behavior across USSD, WhatsApp, HTTP
-3. **Check Character Limits**: Test USSD character restrictions
-4. **Verify Session Management**: Test session boundaries and persistence
-5. **Monitor Request Logs**: Debug integration issues in real-time
-
-#### Performance
-
-- Use simulator for rapid prototyping and debugging
-- Test edge cases and error conditions safely
-- Validate webhook payloads before production deployment
+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.
 
-The FlowChat simulator provides a complete testing environment that accurately simulates real-world platform behavior while offering comprehensive debugging capabilities for efficient development and testing workflows.
+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.
 
+## Related
 
+- [Getting started](getting-started.md)
+- [Configuration](configuration.md)

data/examples/http_controller.rb

@@ -33,20 +33,22 @@ class HttpController < ApplicationController
       config.use_gateway FlowChat::Http::Gateway::Simple
       config.use_session_store FlowChat::Session::CacheSessionStore
 
-      # Configure session management
+      # The HTTP gateway sets request.user_id from the request's user_id, so key
+      # sessions on it. (:msisdn would be nil here, collapsing every caller into
+      # one session.)
       config.use_session_config(
         boundaries: [:flow, :platform],
         hash_identifiers: true,
-        identifier: :msisdn  # Use phone number for durable sessions
+        identifier: :user_id
       )
     end
 
-    processor.run WelcomeFlow, :main_page
+    processor.run HttpWelcomeFlow, :main_page
   end
 end
 
 # Example flow for HTTP gateway
-class WelcomeFlow < FlowChat::Flow
+class HttpWelcomeFlow < FlowChat::Flow
   def main_page
     name = app.screen(:name) do |prompt|
       prompt.ask "Hello! What's your name?",
@@ -87,7 +89,7 @@ class WelcomeFlow < FlowChat::Flow
     if continue
       features_demo
     else
-      app.say "Thanks for trying FlowChat HTTP Gateway! 👋"
+      app.say "Thanks for trying the FlowChat HTTP gateway!"
     end
   end
 
@@ -115,7 +117,7 @@ class WelcomeFlow < FlowChat::Flow
   def media_demo
     app.say "FlowChat supports rich media in HTTP responses!",
       media: {
-        url: "https://via.placeholder.com/300x200.png?text=FlowChat+HTTP",
+        url: "https://example.com/images/flowchat-http-demo.png",
         type: :image,
         caption: "FlowChat HTTP Gateway Demo"
       }
@@ -146,9 +148,9 @@ class WelcomeFlow < FlowChat::Flow
     timestamp = app.session.get("demo_timestamp")
 
     app.say "Session Demo:"
-    app.say "• This is visit ##{counter} in this session"
-    app.say "• Session started at: #{timestamp}"
-    app.say "• Session data persists across HTTP requests"
-    app.say "• Session ID: #{app.session.context["session.id"]}"
+    app.say "This is visit ##{counter} in this session"
+    app.say "Session started at: #{timestamp}"
+    app.say "Session data persists across HTTP requests"
+    app.say "Session ID: #{app.context["session.id"]}"
   end
 end

data/examples/intercom_configuration_example.rb

@@ -21,15 +21,17 @@
 # 3. Named Configuration Example (for multi-tenant apps)
 class MultiTenantIntercomSetup
   def self.setup_configurations
-    # Main company configuration
-    FlowChat::Intercom::Configuration.new("main") do |config|
+    # Passing a name registers the configuration under that name, so you can
+    # fetch it later with Configuration.get(:main). Set attributes with tap;
+    # Configuration.new does not yield a block.
+    FlowChat::Intercom::Configuration.new("main").tap do |config|
       config.access_token = Rails.application.credentials.dig(:intercom, :main, :access_token)
       config.client_secret = Rails.application.credentials.dig(:intercom, :main, :client_secret)
       config.admin_id = Rails.application.credentials.dig(:intercom, :main, :admin_id)
     end
 
     # Enterprise customer configuration
-    FlowChat::Intercom::Configuration.new("enterprise") do |config|
+    FlowChat::Intercom::Configuration.new("enterprise").tap do |config|
       config.access_token = Rails.application.credentials.dig(:intercom, :enterprise, :access_token)
       config.client_secret = Rails.application.credentials.dig(:intercom, :enterprise, :client_secret)
       config.admin_id = Rails.application.credentials.dig(:intercom, :enterprise, :admin_id)
@@ -53,17 +55,17 @@ class TenantAwareIntercomController < ApplicationController
   skip_forgery_protection
 
   def webhook
-    # Get tenant-specific configuration
+    # Fetch the named configuration registered in setup_configurations above.
     tenant = params[:tenant] || "main"
-    FlowChat::Intercom::Configuration.get(tenant)
+    tenant_config = FlowChat::Intercom::Configuration.get(tenant)
 
     processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Intercom::Gateway::IntercomApi, config
+      config.use_gateway FlowChat::Intercom::Gateway::IntercomApi, tenant_config
       config.use_session_store FlowChat::Session::CacheSessionStore
-      config.use_session_config(
-        boundaries: [:flow, :url],  # Separate sessions per tenant
-        identifier: :conversation_id
-      )
+      # request.id is the conversation id (the default :request_id identifier),
+      # so each conversation gets its own session. The :url boundary separates
+      # tenants that share the flow.
+      config.use_session_config(boundaries: [:flow, :url])
     end
 
     processor.run CustomerSupportFlow, :handle_conversation
@@ -95,24 +97,17 @@ end
 #    - Check logs for any signature validation issues
 
 # 7. Finding Your Admin ID (Required)
-# To find your admin ID for message sending, use this Rails console command:
+# The admin_id identifies which admin sends messages to a conversation.
+# FlowChat's own client only sends messages, so list admins with the official
+# intercom gem in a Rails console:
 #
 #   rails console
 #   ```
-#     config = FlowChat::Intercom::Configuration.from_credentials
-#     client = FlowChat::Intercom::Client.new(config)
-#     result = client.list_admins
-#     result["admins"].each { |admin| puts "#{admin["name"]} (#{admin["email"]}) - ID: #{admin["id"]}" }
+#     intercom = Intercom::Client.new(token: Rails.application.credentials.dig(:intercom, :access_token))
+#     intercom.admins.all.each { |admin| puts "#{admin.name} (#{admin.email}) - ID: #{admin.id}" }
 #   ```
 #
-# This will display all admins with their IDs. Copy the ID of the admin you want to use for sending messages.
-#
-# Alternative methods:
-# 1. Go to your Intercom Developer Hub (https://developers.intercom.com/)
-# 2. Navigate to your app → Configure → Basic Information
-# 3. Find the Admin ID in the app details
-#
-# The admin_id is required for sending messages from FlowChat to Intercom conversations.
-# The API uses this to identify which admin is sending the message.
+# Copy the ID of the admin you want to send from. You can also find it in the
+# Intercom Developer Hub under your app's Configure -> Basic Information.
 #
 # Note: The old bot_user_id configuration is no longer needed.

data/examples/intercom_controller.rb

@@ -14,11 +14,10 @@ class IntercomController < ApplicationController
       # Use cache-based session storage for longer-lived sessions
       config.use_session_store FlowChat::Session::CacheSessionStore
 
-      # Configure session boundaries - use conversation ID for session isolation
-      config.use_session_config(
-        boundaries: [:conversation], # Each conversation gets its own session
-        identifier: :conversation_id  # Use conversation ID as session key
-      )
+      # The Intercom gateway sets request.id to the conversation id, and the
+      # default identifier (:request_id) uses it, so each conversation already
+      # gets its own session. Scope by flow as well.
+      config.use_session_config(boundaries: [:flow])
     end
 
     # Run the customer support flow
@@ -29,16 +28,10 @@ end
 # Example flow for handling customer conversations via Intercom
 class CustomerSupportFlow < FlowChat::Flow
   def handle_conversation
-    # Greet the user
-    greeting = if first_message?
-      "Hello! I'm here to help you. How can I assist you today?"
-    else
-      "Thanks for your message! Let me help you with that."
-    end
-
-    # Get the user's inquiry
+    # Ask the opening question. The prompt is only shown on the first unanswered
+    # turn; once the user replies, screen(:inquiry) returns their stored answer.
     inquiry = app.screen(:inquiry) do |prompt|
-      prompt.ask greeting
+      prompt.ask "Hello! I'm here to help you. How can I assist you today?"
     end
 
     # Categorize the inquiry and provide appropriate response
@@ -61,11 +54,6 @@ class CustomerSupportFlow < FlowChat::Flow
 
   private
 
-  def first_message?
-    # Check if this is the first message in the conversation
-    app.session.get("message_count").nil?
-  end
-
   def categorize_inquiry(inquiry)
     # Simple keyword-based categorization
     # In a real app, you might use AI/ML for better categorization
@@ -171,7 +159,7 @@ class CustomerSupportFlow < FlowChat::Flow
   end
 
   def escalate_to_human(reason, team_id: nil)
-    conversation_id = app.context["request.conversation_id"]
+    conversation_id = app.context["request.id"]
 
     # Business logic: Use Intercom manager for conversation control
     if app.gateway == :intercom_api