flow_chat 0.5.2 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a04a5ad026a67e7ce71aa0a22a3b5522da80cf0da4552280853154e91bc1a27
-  data.tar.gz: 515908f7a643eb53dd7ce542aa7005f54eb1127b640b4d3b834f1891137a2d16
+  metadata.gz: 7acb16ea89a86c4680cd499207fe48763bf91de4937b8ad3474ce22c27194ca7
+  data.tar.gz: fc79cb9fffa808baeb2abddf72119536e16661f54cb2644dc04d89f8983fe1b0
 SHA512:
-  metadata.gz: 515db13100618aa0150672a08c960ef08c6661171e926694580c91d3a9d5dc1decf2b6698ae6beca128ae24b3ee314779e82fec3f37a16b97aa5a3e96157b04a
-  data.tar.gz: a1846f20afce50943626bb5c0c617e4e7d5a6fa445d9cd0be4fdfaf5438ab29b3201b6e4c3e90cd9d73feef16bac2607017f0fa8cea5a6b472feb5213a25227a
+  metadata.gz: ae0c2b313390de0311fce7030f4577ea5ae127e8f6241fecd6d7e8c6bf1b210d1aa98a2878accf2ea5069f89dc8fd766ff0fb800e9cddf123ccd7c7aedfd374c
+  data.tar.gz: 462d4f8caeb6a1a9f11809c25195e439bb0ffff174343d07daf7407f765c62740ca40dff5fa9367e1ddb36775ce774d325076ad5ac9bbc3cfe2ef8b7b5e95b67

data/README.md

@@ -77,7 +77,7 @@ class UssdController < ApplicationController
   def process_request
     processor = FlowChat::Ussd::Processor.new(self) do |config|
       config.use_gateway FlowChat::Ussd::Gateway::Nalo
-      config.use_session_store FlowChat::Session::RailsSessionStore
+      config.use_session_store FlowChat::Session::CacheSessionStore
     end
 
     processor.run WelcomeFlow, :main_page
@@ -485,7 +485,7 @@ end
 
 ## Cross-Platform Compatibility
 
-FlowChat provides a unified API that works across both USSD and WhatsApp platforms, with graceful degradation for platform-specific features:
+FlowChat provides a unified API that works across both USSD and WhatsApp platforms, with graceful degradation for platform-specific features. Under the hood, FlowChat uses a unified prompt architecture that ensures consistent behavior across platforms while optimizing the user experience for each channel.
 
 ### Shared Features (Both USSD & WhatsApp)
 - ✅ `app.screen()` - Interactive screens with prompts
@@ -773,6 +773,46 @@ app.screen(:credit_card) do |prompt|
 end
 ```
 
+### Validation Error Display
+
+Configure how validation errors are displayed to users:
+
+```ruby
+# config/initializers/flowchat.rb
+
+# Default behavior: combine error with original message
+FlowChat::Config.combine_validation_error_with_message = true
+# User sees: "Card number must be 16 digits\n\nEnter credit card number:"
+
+# Show only the error message
+FlowChat::Config.combine_validation_error_with_message = false  
+# User sees: "Card number must be 16 digits"
+```
+
+**Use cases for each approach:**
+
+- **Combined (default)**: Better for first-time users who need context about what they're entering
+- **Error only**: Cleaner UX for experienced users, reduces message length for USSD character limits
+
+**Example with both approaches:**
+
+```ruby
+# This validation code works the same way regardless of config
+age = app.screen(:age) do |prompt|
+  prompt.ask "How old are you?",
+    convert: ->(input) { input.to_i },
+    validate: ->(input) { "You must be at least 18 years old" unless input >= 18 }
+end
+
+# With combine_validation_error_with_message = true (default):
+# "You must be at least 18 years old
+# 
+# How old are you?"
+
+# With combine_validation_error_with_message = false:
+# "You must be at least 18 years old"
+```
+
 ### Background Job Support
 
 For high-volume WhatsApp applications, use background response delivery:
@@ -861,7 +901,7 @@ processor = FlowChat::Ussd::Processor.new(self) do |config|
   config.use_gateway FlowChat::Ussd::Gateway::Nalo
   
   # Session storage (required)
-  config.use_session_store FlowChat::Session::RailsSessionStore
+  config.use_session_store FlowChat::Session::CacheSessionStore
   
   # Add custom middleware (optional)
   config.use_middleware MyLoggingMiddleware
@@ -906,7 +946,7 @@ FlowChat::Config.ussd.pagination_back_text = "Back"     # Default: "Back"
 ```ruby
 processor = FlowChat::Ussd::Processor.new(self) do |config|
   config.use_gateway FlowChat::Ussd::Gateway::Nalo
-  config.use_session_store FlowChat::Session::RailsSessionStore
+  config.use_session_store FlowChat::Session::CacheSessionStore
   config.use_resumable_sessions  # Enable resumable sessions
 end
 ```
@@ -933,7 +973,7 @@ end
 # Use your custom middleware
 processor = FlowChat::Ussd::Processor.new(self) do |config|
   config.use_gateway FlowChat::Ussd::Gateway::Nalo
-  config.use_session_store FlowChat::Session::RailsSessionStore
+  config.use_session_store FlowChat::Session::CacheSessionStore
   config.use_middleware LoggingMiddleware
 end
 ```
@@ -1085,6 +1125,11 @@ FlowChat::Config.logger = Rails.logger
 FlowChat::Config.cache = Rails.cache
 FlowChat::Config.simulator_secret = "your_secure_secret_here"
 
+# Validation error display behavior
+# When true (default), validation errors are combined with the original message.
+# When false, only the validation error message is shown to the user.
+FlowChat::Config.combine_validation_error_with_message = true
+
 # USSD configuration
 FlowChat::Config.ussd.pagination_page_size = 140
 FlowChat::Config.ussd.pagination_next_option = "#"

data/app/controllers/demo_controller.rb

@@ -0,0 +1,101 @@
+# Demo Controller - Showcases FlowChat comprehensive features
+# 
+# This controller demonstrates how to use the DemoRestaurantFlow
+# across both USSD and WhatsApp platforms, showing off all FlowChat features.
+#
+# Features demonstrated:
+# - Cross-platform compatibility
+# - Media support with graceful degradation  
+# - Complex workflows with session management
+# - Input validation and transformation
+# - Rich interactive elements
+
+class DemoController < ApplicationController
+  skip_forgery_protection
+
+  # USSD Demo Endpoint
+  # Usage: POST /demo/ussd
+  def ussd_demo
+    processor = FlowChat::Ussd::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Ussd::Gateway::Nalo
+      config.use_session_store FlowChat::Session::RailsSessionStore
+      
+      # Optional: Enable resumable sessions for better UX
+      config.use_resumable_sessions
+      
+      # Optional: Custom pagination settings for large menus
+      FlowChat::Config.ussd.pagination_page_size = 120  # Slightly larger for demo
+    end
+
+    processor.run DemoRestaurantFlow, :main_page
+  end
+
+  # WhatsApp Demo Endpoint  
+  # Usage: GET/POST /demo/whatsapp
+  def whatsapp_demo
+    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: Rails.env.development?) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run DemoRestaurantFlow, :main_page
+  end
+
+  # Alternative WhatsApp Demo with Custom Configuration
+  # Usage: GET/POST /demo/whatsapp_custom
+  def whatsapp_custom_demo
+    # Custom configuration for multi-tenant demo
+    custom_config = FlowChat::Whatsapp::Configuration.new
+    custom_config.access_token = ENV['DEMO_WHATSAPP_ACCESS_TOKEN']
+    custom_config.phone_number_id = ENV['DEMO_WHATSAPP_PHONE_NUMBER_ID']
+    custom_config.verify_token = ENV['DEMO_WHATSAPP_VERIFY_TOKEN']
+    custom_config.app_secret = ENV['DEMO_WHATSAPP_APP_SECRET']
+    custom_config.skip_signature_validation = Rails.env.development?
+
+    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: true) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, custom_config
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run DemoRestaurantFlow, :main_page
+  end
+
+  # Background Mode Demo
+  # Usage: GET/POST /demo/whatsapp_background
+  def whatsapp_background_demo
+    # Configure for background processing
+    original_mode = FlowChat::Config.whatsapp.message_handling_mode
+    FlowChat::Config.whatsapp.message_handling_mode = :background
+    FlowChat::Config.whatsapp.background_job_class = 'DemoWhatsappJob'
+
+    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run DemoRestaurantFlow, :main_page
+
+  ensure
+    # Restore original mode
+    FlowChat::Config.whatsapp.message_handling_mode = original_mode
+  end
+
+  # Simulator Mode Demo (for testing)
+  # Usage: GET/POST /demo/whatsapp_simulator
+  def whatsapp_simulator_demo
+    # Force simulator mode for testing
+    original_mode = FlowChat::Config.whatsapp.message_handling_mode
+    FlowChat::Config.whatsapp.message_handling_mode = :simulator
+
+    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: true) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run DemoRestaurantFlow, :main_page
+
+  ensure
+    # Restore original mode
+    FlowChat::Config.whatsapp.message_handling_mode = original_mode
+  end
+end