flow_chat 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38bdb327e3213bbb5ca4986453b395fc7d4df7666a9e5c251469ded12bea90a7
-  data.tar.gz: f0b6d567e4f75a8945d5e125cc2198396b06827d8f212c7e6a38894a78110c6a
+  metadata.gz: c175da6eda53d8aede833db06dd560278a8276254877c3a407230cc73f6db8bc
+  data.tar.gz: 631339558c79d26a6c1013e4946a23415fb31e45752f02ab4b0edad980afea8e
 SHA512:
-  metadata.gz: 578743345bb3a509551f4cdb72d487e565a1a93bd8410a7f0b1664dabe8f5da8f5e6b96991e8108e363124e004ea9d4cb8baa5c9e6d5abc9d4c3df6cd995a287
-  data.tar.gz: 6faf7ccb278d68559ba4cd5581d33b86e871f8dac764607d46dfebe39f86e2e4266f0369380e177f3969723083a94bb000dd3411a573e52cd17b84a7f9b3dc6a
+  metadata.gz: 6893e1040fb1c1e1316d1e242787c6616128a2c4be7c4c0f78b99d4e3b27567ff886d1c4035f35442e6dd6497d5a11da0f3564407bb0a2d2ee3ee33358527ed9
+  data.tar.gz: 0b32ee8a7e375758da178e0bb51411e4f980541ab37de7ddfb470a9abe3500141af81e0b0f02464a066675a7a18c3eced9e89b97f465b661e9b0297482edc846

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