flow_chat 0.6.1 → 0.8.0

data/docs/configuration.md

@@ -0,0 +1,360 @@
+# Configuration Reference
+
+This document covers all FlowChat configuration options.
+
+## Framework Configuration
+
+```ruby
+# config/initializers/flowchat.rb
+
+# Core configuration
+FlowChat::Config.logger = Rails.logger
+FlowChat::Config.cache = Rails.cache
+FlowChat::Config.simulator_secret = "your_secure_secret_here"
+
+# Validation error display behavior
+FlowChat::Config.combine_validation_error_with_message = true  # default
+
+# Setup instrumentation (optional)
+FlowChat.setup_instrumentation!
+```
+
+## Session Configuration
+
+```ruby
+# Session boundaries control how session IDs are constructed
+FlowChat::Config.session.boundaries = [:flow, :platform]  # default
+FlowChat::Config.session.hash_phone_numbers = true        # hash phone numbers for privacy
+FlowChat::Config.session.identifier = nil                 # let platforms choose (default)
+
+# Available boundary options:
+# :flow - separate sessions per flow class
+# :platform - separate sessions per platform (ussd, whatsapp)  
+# :gateway - separate sessions per gateway
+# [] - global sessions (no boundaries)
+
+# Available identifier options:
+# nil - platform chooses default (:request_id for USSD, :msisdn for WhatsApp)
+# :msisdn - use phone number (durable sessions)
+# :request_id - use request ID (ephemeral sessions)
+```
+
+## USSD Configuration
+
+```ruby
+# USSD pagination settings
+FlowChat::Config.ussd.pagination_page_size = 140          # characters per page
+FlowChat::Config.ussd.pagination_next_option = "#"        # option to go to next page
+FlowChat::Config.ussd.pagination_next_text = "More"       # text for next option
+FlowChat::Config.ussd.pagination_back_option = "0"        # option to go back
+FlowChat::Config.ussd.pagination_back_text = "Back"       # text for back option
+```
+
+## WhatsApp Configuration
+
+```ruby
+# Message handling modes
+FlowChat::Config.whatsapp.message_handling_mode = :inline  # :inline, :background, :simulator
+FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+```
+
+### WhatsApp Credential Configuration
+
+#### Option 1: Rails Credentials
+
+```bash
+rails credentials:edit
+```
+
+```yaml
+whatsapp:
+  access_token: "your_access_token"
+  phone_number_id: "your_phone_number_id"
+  verify_token: "your_verify_token"
+  app_id: "your_app_id"
+  app_secret: "your_app_secret"
+  business_account_id: "your_business_account_id"
+  skip_signature_validation: false
+```
+
+#### Option 2: Environment Variables
+
+```bash
+export WHATSAPP_ACCESS_TOKEN="your_access_token"
+export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id" 
+export WHATSAPP_VERIFY_TOKEN="your_verify_token"
+export WHATSAPP_APP_ID="your_app_id"
+export WHATSAPP_APP_SECRET="your_app_secret"
+export WHATSAPP_BUSINESS_ACCOUNT_ID="your_business_account_id"
+export WHATSAPP_SKIP_SIGNATURE_VALIDATION="false"
+```
+
+#### Option 3: Programmatic Configuration
+
+```ruby
+config = FlowChat::Whatsapp::Configuration.new(:my_config)  # Named configuration
+config.access_token = "your_access_token"
+config.phone_number_id = "your_phone_number_id"
+config.verify_token = "your_verify_token"
+config.app_id = "your_app_id"
+config.app_secret = "your_app_secret"
+config.business_account_id = "your_business_account_id"
+config.skip_signature_validation = false
+# Configuration is automatically registered as :my_config
+```
+
+**⚠️ Important for Background Jobs:** When using background mode with programmatic configurations, you must register them in an initializer:
+
+```ruby
+# config/initializers/whatsapp_configs.rb
+# Register configurations so background jobs can access them
+production_config = FlowChat::Whatsapp::Configuration.new(:production)
+production_config.access_token = ENV['PROD_WHATSAPP_TOKEN']
+# ... other settings
+
+staging_config = FlowChat::Whatsapp::Configuration.new(:staging)  
+staging_config.access_token = ENV['STAGING_WHATSAPP_TOKEN']
+# ... other settings
+```
+
+Then use named configurations in controllers:
+
+```ruby
+# Use registered configuration
+config = FlowChat::Whatsapp::Configuration.get(:production)
+processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, config
+end
+```
+
+## Security Configuration
+
+### WhatsApp Security
+
+```ruby
+# Production security (recommended)
+config.app_secret = "your_whatsapp_app_secret"
+config.skip_signature_validation = false  # default
+
+# Development mode (disable validation)
+config.app_secret = nil
+config.skip_signature_validation = true
+```
+
+### Simulator Security
+
+```ruby
+# Use Rails secret for uniqueness
+FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_simulator"
+
+# Or use dedicated secret
+FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
+```
+
+## Environment-Specific Configuration
+
+```ruby
+# config/initializers/flowchat.rb
+case Rails.env
+when 'development'
+  FlowChat::Config.whatsapp.message_handling_mode = :simulator
+  FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_dev"
+  
+when 'test'
+  FlowChat::Config.whatsapp.message_handling_mode = :simulator
+  FlowChat::Config.simulator_secret = "test_secret"
+  
+when 'staging'
+  FlowChat::Config.whatsapp.message_handling_mode = :inline
+  FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
+  
+when 'production'
+  FlowChat::Config.whatsapp.message_handling_mode = :background
+  FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+  FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
+end
+```
+
+## Processor Configuration
+
+### USSD Processor
+
+```ruby
+processor = FlowChat::Ussd::Processor.new(self) do |config|
+  # Gateway (required)
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  
+  # Session storage (required)
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  
+  # Optional middleware
+  config.use_middleware MyCustomMiddleware
+  
+  # Configure session boundaries
+  config.use_session_config(
+    boundaries: [:flow, :platform],     # which boundaries to enforce
+    hash_phone_numbers: true,           # hash phone numbers for privacy
+    identifier: :msisdn                 # use MSISDN for durable sessions (optional)
+  )
+  
+  # Shorthand for durable sessions (identifier: :msisdn)
+  config.use_durable_sessions
+end
+```
+
+### WhatsApp Processor
+
+```ruby
+processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: Rails.env.development?) do |config|
+  # Gateway (required)
+  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+  
+  # Session storage (required)  
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  
+  # Optional custom configuration
+  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, custom_whatsapp_config
+end
+```
+
+## Session Store Options
+
+### Cache Session Store
+
+```ruby
+config.use_session_store FlowChat::Session::CacheSessionStore
+```
+
+Uses Rails cache backend with automatic TTL management. This is the primary session store available in FlowChat.
+
+## Middleware Configuration
+
+### Built-in Middleware
+
+```ruby
+# Pagination (USSD only, automatic)
+FlowChat::Ussd::Middleware::Pagination
+
+# Session management (automatic)
+FlowChat::Session::Middleware
+
+# Gateway communication (automatic)
+FlowChat::Ussd::Gateway::Nalo
+FlowChat::Whatsapp::Gateway::CloudApi
+```
+
+### Custom Middleware
+
+```ruby
+class LoggingMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(context)
+    Rails.logger.info "Processing request: #{context.input}"
+    result = @app.call(context)
+    Rails.logger.info "Response: #{result[1]}"
+    result
+  end
+end
+
+# Use custom middleware
+config.use_middleware LoggingMiddleware
+```
+
+## Validation Configuration
+
+### Error Display Options
+
+```ruby
+# Combine validation error with original message (default)
+FlowChat::Config.combine_validation_error_with_message = true
+# User sees: "Invalid email format\n\nEnter your email:"
+
+# Show only validation error
+FlowChat::Config.combine_validation_error_with_message = false
+# User sees: "Invalid email format"
+```
+
+## Background Job Configuration
+
+### Job Class Setup
+
+```ruby
+# app/jobs/whatsapp_message_job.rb
+class WhatsappMessageJob < ApplicationJob
+  include FlowChat::Whatsapp::SendJobSupport
+
+  def perform(send_data)
+    perform_whatsapp_send(send_data)
+  end
+end
+```
+
+**Configuration Resolution:** The job automatically resolves configurations using:
+1. Named configuration from `send_data[:configuration_name]` if present
+2. Default configuration from credentials/environment variables
+
+For custom resolution logic, override the configuration resolution:
+
+```ruby
+class CustomWhatsappMessageJob < ApplicationJob
+  include FlowChat::Whatsapp::SendJobSupport
+
+  def perform(send_data)
+    perform_whatsapp_send(send_data)
+  end
+
+  private
+
+  def resolve_whatsapp_configuration(send_data)
+    # Custom logic to resolve configuration
+    tenant_id = ...
+    FlowChat::Whatsapp::Configuration.get("tenant_#{tenant_id}")
+  end
+end
+```
+
+### Queue Configuration
+
+```ruby
+# config/application.rb
+config.active_job.queue_adapter = :sidekiq
+
+# config/initializers/flowchat.rb
+FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+```
+
+## Instrumentation Configuration
+
+### Basic Setup
+
+```ruby
+# Enable instrumentation
+FlowChat.setup_instrumentation!
+```
+
+### Custom Event Subscribers
+
+```ruby
+# Subscribe to specific events
+ActiveSupport::Notifications.subscribe("flow.execution.end.flow_chat") do |event|
+  # Custom handling
+  ExternalMonitoring.track_flow_execution(
+    event.payload[:flow_name], 
+    event.duration
+  )
+end
+
+# Subscribe to all FlowChat events
+ActiveSupport::Notifications.subscribe(/\.flow_chat$/) do |name, start, finish, id, payload|
+  CustomLogger.log_event(name, payload.merge(duration: finish - start))
+end
+```
+
+## Configuration Validation
+
+FlowChat validates configuration at runtime and provides helpful error messages:
+
+FlowChat validates configuration at runtime and provides helpful error messages for missing or invalid configurations. 

data/docs/flows.md

@@ -0,0 +1,320 @@
+# Flow Development Guide
+
+This guide covers advanced flow patterns, validation techniques, and best practices for building sophisticated conversational workflows.
+
+## Flow Architecture
+
+### Flow Lifecycle
+
+Every flow method must result in user interaction:
+
+```ruby
+class ExampleFlow < FlowChat::Flow
+  def main_page
+    # ✅ Always end with user interaction
+    choice = app.screen(:choice) { |p| p.select "Choose:", ["A", "B"] }
+    
+    case choice
+    when "A"
+      handle_option_a
+      app.say "Option A completed!"  # Required interaction
+    when "B"  
+      handle_option_b
+      app.say "Option B completed!"  # Required interaction
+    end
+  end
+end
+```
+
+### Session Management
+
+FlowChat automatically persists screen results:
+
+```ruby
+class RegistrationFlow < FlowChat::Flow
+  def main_page
+    # These values persist across requests
+    name = app.screen(:name) { |p| p.ask "Name?" }
+    email = app.screen(:email) { |p| p.ask "Email?" }
+    
+    # Show summary using cached values
+    confirmed = app.screen(:confirm) do |prompt|
+      prompt.yes? "Create account for #{name} (#{email})?"
+    end
+    
+    if confirmed
+      create_user(name: name, email: email)
+      app.say "Account created!"
+    end
+  end
+end
+```
+
+## Input Validation Patterns
+
+### Basic Validation
+
+```ruby
+age = app.screen(:age) do |prompt|
+  prompt.ask "Enter your age:",
+    validate: ->(input) { 
+      return "Age must be a number" unless input.match?(/^\d+$/)
+      return "Must be 18 or older" unless input.to_i >= 18
+      nil  # Return nil for valid input
+    },
+    transform: ->(input) { input.to_i }
+end
+```
+
+### Complex Validation
+
+```ruby
+phone = app.screen(:phone) do |prompt|
+  prompt.ask "Enter phone number:",
+    validate: ->(input) {
+      clean = input.gsub(/[\s\-\(\)]/, '')
+      return "Invalid format" unless clean.match?(/^\+?[\d]{10,15}$/)
+      return "Must start with country code" unless clean.start_with?('+')
+      nil
+    },
+    transform: ->(input) { input.gsub(/[\s\-\(\)]/, '') }
+end
+```
+
+### Conditional Validation
+
+```ruby
+class PaymentFlow < FlowChat::Flow
+  def collect_payment_method
+    method = app.screen(:method) do |prompt|
+      prompt.select "Payment method:", ["card", "mobile_money"]
+    end
+    
+    if method == "card"
+      collect_card_details
+    else
+      collect_mobile_money_details
+    end
+  end
+  
+  private
+  
+  def collect_card_details
+    card = app.screen(:card) do |prompt|
+      prompt.ask "Card number (16 digits):",
+        validate: ->(input) {
+          clean = input.gsub(/\s/, '')
+          return "Must be 16 digits" unless clean.length == 16
+          return "Invalid card number" unless luhn_valid?(clean)
+          nil
+        }
+    end
+    
+    app.say "Card ending in #{card[-4..-1]} saved."
+  end
+end
+```
+
+## Menu Patterns
+
+### Dynamic Menus
+
+```ruby
+def show_products
+  products = fetch_available_products
+  
+  choice = app.screen(:product) do |prompt|
+    prompt.select "Choose product:", products.map(&:name)
+  end
+  
+  selected_product = products.find { |p| p.name == choice }
+  show_product_details(selected_product)
+end
+```
+
+### Nested Menus
+
+```ruby
+def main_menu
+  choice = app.screen(:main) do |prompt|
+    prompt.select "Main Menu:", {
+      "products" => "View Products",
+      "orders" => "My Orders", 
+      "support" => "Customer Support"
+    }
+  end
+  
+  case choice
+  when "products"
+    products_menu
+  when "orders"
+    orders_menu
+  when "support"
+    support_menu
+  end
+end
+```
+
+## Advanced Patterns
+
+### Multi-Step Forms
+
+```ruby
+class CompleteProfileFlow < FlowChat::Flow
+  def main_page
+    collect_basic_info
+    collect_preferences
+    confirm_and_save
+  end
+  
+  private
+  
+  def collect_basic_info
+    app.screen(:name) { |p| p.ask "Full name:" }
+    app.screen(:email) { |p| p.ask "Email:" }
+    app.screen(:phone) { |p| p.ask "Phone:" }
+  end
+  
+  def collect_preferences
+    app.screen(:language) { |p| p.select "Language:", ["English", "French"] }
+    app.screen(:notifications) { |p| p.yes? "Enable notifications?" }
+  end
+  
+  def confirm_and_save
+    summary = build_summary
+    confirmed = app.screen(:confirm) { |p| p.yes? "Save profile?\n\n#{summary}" }
+    
+    if confirmed
+      save_profile
+      app.say "Profile saved successfully!"
+    else
+      app.say "Profile not saved."
+    end
+  end
+end
+```
+
+### Error Recovery
+
+```ruby
+def process_payment
+  begin
+    amount = app.screen(:amount) do |prompt|
+      prompt.ask "Amount to pay:",
+        validate: ->(input) {
+          return "Invalid amount" unless input.match?(/^\d+(\.\d{2})?$/)
+          return "Minimum $1.00" unless input.to_f >= 1.0
+          nil
+        },
+        transform: ->(input) { input.to_f }
+    end
+    
+    process_transaction(amount)
+    app.say "Payment of $#{amount} processed successfully!"
+    
+  rescue PaymentError => e
+    app.say "Payment failed: #{e.message}. Please try again."
+    process_payment  # Retry
+  end
+end
+```
+
+## Cross-Platform Considerations
+
+### Platform Detection
+
+```ruby
+def show_help
+  if app.context["request.gateway"] == :whatsapp_cloud_api
+    # WhatsApp users get rich media
+    app.say "Here's how to use our service:",
+      media: { type: :image, url: "https://example.com/help.jpg" }
+  else
+    # USSD users get text with link
+    app.say "Help guide: https://example.com/help"
+  end
+end
+```
+
+### Progressive Enhancement
+
+```ruby
+def collect_feedback
+  rating = app.screen(:rating) do |prompt|
+    if whatsapp?
+      # Rich interactive buttons for WhatsApp
+      prompt.select "Rate our service:", {
+        "5" => "⭐⭐⭐⭐⭐ Excellent",
+        "4" => "⭐⭐⭐⭐ Good", 
+        "3" => "⭐⭐⭐ Average",
+        "2" => "⭐⭐ Poor",
+        "1" => "⭐ Very Poor"
+      }
+    else
+      # Simple numbered list for USSD
+      prompt.select "Rate our service (1-5):", ["1", "2", "3", "4", "5"]
+    end
+  end
+  
+  app.say "Thank you for rating us #{rating} stars!"
+end
+
+private
+
+def whatsapp?
+  app.context["request.gateway"] == :whatsapp_cloud_api
+end
+```
+
+## Best Practices
+
+### Keep Methods Focused
+
+```ruby
+# ✅ Good: Single responsibility
+def collect_contact_info
+  name = app.screen(:name) { |p| p.ask "Name:" }
+  email = app.screen(:email) { |p| p.ask "Email:" }
+  { name: name, email: email }
+end
+
+# ❌ Avoid: Too much in one method
+def handle_everything
+  # 50+ lines of mixed logic
+end
+```
+
+### Use Meaningful Screen Names
+
+```ruby
+# ✅ Good: Descriptive names
+app.screen(:billing_address) { |p| p.ask "Billing address:" }
+app.screen(:confirm_payment) { |p| p.yes? "Confirm $#{amount}?" }
+
+# ❌ Avoid: Generic names  
+app.screen(:input1) { |p| p.ask "Address:" }
+app.screen(:confirm) { |p| p.yes? "OK?" }
+```
+
+### Handle Edge Cases
+
+```ruby
+def show_order_history
+  orders = fetch_user_orders
+  
+  if orders.empty?
+    app.say "You have no previous orders."
+    return
+  end
+  
+  choice = app.screen(:order) do |prompt|
+    prompt.select "Select order:", orders.map(&:display_name)
+  end
+  
+  show_order_details(orders.find { |o| o.display_name == choice })
+end
+```
+
+## Testing Flows
+
+See [Testing Guide](testing.md) for comprehensive testing strategies.