flow_chat 0.8.2 → 0.9.0

data/docs/ussd-setup.md

@@ -1,322 +0,0 @@
-# USSD Setup Guide
-
-This guide covers USSD configuration and implementation patterns for FlowChat.
-
-## Basic Setup
-
-### 1. Create a Flow
-
-Create a flow in `app/flow_chat/welcome_flow.rb`:
-
-```ruby
-class WelcomeFlow < FlowChat::Flow
-  def main_page
-    name = app.screen(:name) do |prompt|
-      prompt.ask "Welcome! What's your name?",
-        transform: ->(input) { input.strip.titleize }
-    end
-
-    service = app.screen(:service) do |prompt|
-      prompt.select "Choose a service:", {
-        "balance" => "Check Balance",
-        "transfer" => "Transfer Money",
-        "history" => "Transaction History"
-      }
-    end
-
-    case service
-    when "balance"
-      show_balance
-    when "transfer"
-      transfer_money
-    when "history"
-      show_history
-    end
-  end
-
-  private
-
-  def show_balance
-    # Simulate balance check
-    balance = fetch_user_balance(app.phone_number)
-    app.say "Hello #{app.session.get(:name)}! Your balance is $#{balance}."
-  end
-end
-```
-
-### 2. Create Controller
-
-```ruby
-class UssdController < ApplicationController
-  skip_forgery_protection
-
-  def process_request
-    processor = FlowChat::Ussd::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Ussd::Gateway::Nalo
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
-
-    processor.run WelcomeFlow, :main_page
-  end
-end
-```
-
-### 3. Configure Routes
-
-```ruby
-# config/routes.rb
-Rails.application.routes.draw do
-  post 'ussd' => 'ussd#process_request'
-end
-```
-
-## Gateway Configuration
-
-### Nalo Gateway
-
-FlowChat currently supports Nalo USSD gateways:
-
-```ruby
-processor = FlowChat::Ussd::Processor.new(self) do |config|
-  config.use_gateway FlowChat::Ussd::Gateway::Nalo
-  config.use_session_store FlowChat::Session::CacheSessionStore
-end
-```
-
-The Nalo gateway expects these parameters in the request:
-- `msisdn` - User's phone number
-- `input` - User's input text
-- `session_id` - Session identifier
-
-## Pagination
-
-USSD messages are automatically paginated when they exceed character limits:
-
-```ruby
-# Configure pagination behavior
-FlowChat::Config.ussd.pagination_page_size = 140        # characters per page
-FlowChat::Config.ussd.pagination_next_option = "#"      # option for next page
-FlowChat::Config.ussd.pagination_next_text = "More"     # text for next option
-FlowChat::Config.ussd.pagination_back_option = "0"      # option for previous page
-FlowChat::Config.ussd.pagination_back_text = "Back"     # text for back option
-```
-
-### Example Long Message
-
-```ruby
-def show_terms
-  terms = "Very long terms and conditions text that exceeds 140 characters..."
-  app.say terms  # Automatically paginated
-end
-```
-
-**USSD Output:**
-```
-Terms and Conditions:
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt...
-
-# More
-0 Back
-```
-
-## Session Management
-
-Configure session behavior for better user experience:
-
-```ruby
-processor = FlowChat::Ussd::Processor.new(self) do |config|
-  config.use_gateway FlowChat::Ussd::Gateway::Nalo
-  config.use_session_store FlowChat::Session::CacheSessionStore
-  
-  # Enable durable sessions (shorthand)
-  config.use_durable_sessions
-end
-```
-
-### Session Boundaries
-
-Session boundaries control how session IDs are constructed:
-
-- **`:flow`** - Separate sessions per flow class
-- **`:platform`** - Separate USSD from WhatsApp sessions  
-- **`:gateway`** - Separate sessions per gateway
-- **`[]`** - Global sessions (no boundaries)
-
-Session 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)
-- **`hash_identifiers`** - Hash identifiers for privacy (recommended)
-
-## Middleware
-
-### Custom Middleware
-
-```ruby
-class AuthenticationMiddleware
-  def initialize(app)
-    @app = app
-  end
-
-  def call(context)
-    phone = context["request.msisdn"]
-    
-    unless user_exists?(phone)
-      # Return appropriate response for unregistered user
-      return [:prompt, "Please register first. Visit our website to sign up.", nil, nil]
-    end
-    
-    @app.call(context)
-  end
-
-  private
-
-  def user_exists?(phone)
-    User.exists?(phone: phone)
-  end
-end
-
-# Use custom middleware
-processor = FlowChat::Ussd::Processor.new(self) do |config|
-  config.use_gateway FlowChat::Ussd::Gateway::Nalo
-  config.use_session_store FlowChat::Session::CacheSessionStore
-  config.use_middleware AuthenticationMiddleware
-end
-```
-
-## Advanced Patterns
-
-### Menu-Driven Navigation
-
-```ruby
-class MenuFlow < FlowChat::Flow
-  def main_page
-    choice = app.screen(:main_menu) do |prompt|
-      prompt.select "Main Menu:", {
-        "1" => "Account Services",
-        "2" => "Transfer Services", 
-        "3" => "Customer Support"
-      }
-    end
-
-    case choice
-    when "1"
-      account_services
-    when "2"
-      transfer_services
-    when "3"
-      customer_support
-    end
-  end
-
-  def account_services
-    choice = app.screen(:account_menu) do |prompt|
-      prompt.select "Account Services:", {
-        "1" => "Check Balance",
-        "2" => "Mini Statement",
-        "0" => "Back to Main Menu"
-      }
-    end
-
-    case choice
-    when "1"
-      check_balance
-    when "2"
-      mini_statement
-    when "0"
-      main_page  # Return to main menu
-    end
-  end
-end
-```
-
-### Error Handling
-
-```ruby
-def transfer_money
-  begin
-    amount = app.screen(:amount) do |prompt|
-      prompt.ask "Enter amount:",
-        validate: ->(input) {
-          return "Amount must be numeric" unless input.match?(/^\d+(\.\d{2})?$/)
-          return "Minimum transfer is $1" unless input.to_f >= 1.0
-          nil
-        },
-        transform: ->(input) { input.to_f }
-    end
-
-    recipient = app.screen(:recipient) do |prompt|
-      prompt.ask "Enter recipient phone number:",
-        validate: ->(input) {
-          return "Invalid phone number" unless valid_phone?(input)
-          nil
-        }
-    end
-
-    process_transfer(amount, recipient)
-    app.say "Transfer of $#{amount} to #{recipient} successful!"
-
-  rescue TransferError => e
-    app.say "Transfer failed: #{e.message}. Please try again."
-    transfer_money  # Retry
-  end
-end
-```
-
-### Session Data Management
-
-```ruby
-class RegistrationFlow < FlowChat::Flow
-  def main_page
-    collect_personal_info
-    collect_preferences
-    confirm_and_save
-  end
-
-  private
-
-  def collect_personal_info
-    app.screen(:first_name) { |p| p.ask "First name:" }
-    app.screen(:last_name) { |p| p.ask "Last name:" }
-    app.screen(:email) { |p| p.ask "Email address:" }
-  end
-
-  def collect_preferences
-    app.screen(:language) { |p| p.select "Language:", ["English", "French"] }
-    app.screen(:notifications) { |p| p.yes? "Enable SMS notifications?" }
-  end
-
-  def confirm_and_save
-    summary = build_summary_from_session
-    confirmed = app.screen(:confirm) { |p| p.yes? "Save profile?\n\n#{summary}" }
-
-    if confirmed
-      save_user_profile
-      app.say "Registration complete!"
-    else
-      app.say "Registration cancelled."
-    end
-  end
-
-  def build_summary_from_session
-    first_name = app.session.get(:first_name)
-    last_name = app.session.get(:last_name)
-    email = app.session.get(:email)
-    language = app.session.get(:language)
-    
-    "Name: #{first_name} #{last_name}\nEmail: #{email}\nLanguage: #{language}"
-  end
-end
-```
-
-## Testing USSD Flows
-
-Use the built-in simulator for testing USSD flows:
-
-```ruby
-# config/initializers/flowchat.rb
-FlowChat::Config.simulator_secret = "your_secure_secret"
-```
-
-See [Testing Guide](testing.md) for comprehensive testing strategies and [examples/ussd_controller.rb](../examples/ussd_controller.rb) for complete implementation examples. 

data/docs/whatsapp-setup.md

@@ -1,162 +0,0 @@
-# WhatsApp Setup Guide
-
-This guide covers comprehensive WhatsApp configuration for FlowChat, including security, multi-tenant setups, and different processing modes.
-
-## Credential Configuration
-
-FlowChat supports multiple ways to configure WhatsApp credentials:
-
-### 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  # Set to true only for development/testing
-```
-
-### 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: Per-Setup Configuration
-
-For multi-tenant applications:
-
-```ruby
-custom_config = FlowChat::Whatsapp::Configuration.new
-custom_config.access_token = "your_specific_access_token"
-custom_config.phone_number_id = "your_specific_phone_number_id"
-custom_config.verify_token = "your_specific_verify_token"
-custom_config.app_id = "your_specific_app_id"
-custom_config.app_secret = "your_specific_app_secret"
-custom_config.business_account_id = "your_specific_business_account_id"
-custom_config.skip_signature_validation = false
-
-processor = FlowChat::Whatsapp::Processor.new(self) do |config|
-  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, custom_config
-  config.use_session_store FlowChat::Session::CacheSessionStore
-end
-```
-
-## Message Handling Modes
-
-Configure message processing behavior in `config/initializers/flowchat.rb`:
-
-### Inline Mode (Default)
-
-Process messages synchronously:
-
-```ruby
-FlowChat::Config.whatsapp.message_handling_mode = :inline
-```
-
-### Background Mode
-
-Process flows synchronously, send responses asynchronously:
-
-```ruby
-FlowChat::Config.whatsapp.message_handling_mode = :background
-FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
-```
-
-### Simulator Mode
-
-Return response data instead of sending via WhatsApp API:
-
-```ruby
-FlowChat::Config.whatsapp.message_handling_mode = :simulator
-```
-
-## Security Configuration
-
-### Webhook Signature Validation (Production)
-
-```ruby
-custom_config.app_secret = "your_whatsapp_app_secret"
-custom_config.skip_signature_validation = false  # Default: enforce validation
-```
-
-### Development Mode
-
-```ruby
-custom_config.app_secret = nil
-custom_config.skip_signature_validation = true  # Disable validation
-```
-
-⚠️ **Security Warning**: Only disable signature validation in development/testing environments.
-
-## Multi-Tenant Setup
-
-See [examples/multi_tenant_whatsapp_controller.rb](../examples/multi_tenant_whatsapp_controller.rb) for a complete multi-tenant implementation.
-
-## Background Job Setup
-
-When using background jobs with programmatic WhatsApp configurations, you must register configurations in an initializer so they're available to background jobs:
-
-```ruby
-# config/initializers/whatsapp_configs.rb
-tenant_a_config = FlowChat::Whatsapp::Configuration.new(:tenant_a)
-tenant_a_config.access_token = "tenant_a_token"
-tenant_a_config.phone_number_id = "tenant_a_phone"
-tenant_a_config.verify_token = "tenant_a_verify"
-tenant_a_config.app_secret = "tenant_a_secret"
-# Configuration is automatically registered as :tenant_a
-
-tenant_b_config = FlowChat::Whatsapp::Configuration.new(:tenant_b)
-tenant_b_config.access_token = "tenant_b_token"
-tenant_b_config.phone_number_id = "tenant_b_phone"
-tenant_b_config.verify_token = "tenant_b_verify"
-tenant_b_config.app_secret = "tenant_b_secret"
-# Configuration is automatically registered as :tenant_b
-```
-
-Then reference the named configuration in your controller:
-
-```ruby
-processor = FlowChat::Whatsapp::Processor.new(self) do |config|
-  # Use registered configuration by name
-  tenant_config = FlowChat::Whatsapp::Configuration.get(:tenant_a)
-  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, tenant_config
-  config.use_session_store FlowChat::Session::CacheSessionStore
-end
-```
-
-**Why this is required:** Background jobs run in a separate context and cannot access configurations created in controller actions. Registered configurations are globally available.
-
-**Alternative:** Override the job's configuration resolution logic (see examples).
-
-See [examples/whatsapp_message_job.rb](../examples/whatsapp_message_job.rb) for job implementation and [Background Jobs Guide](background-jobs.md) for detailed setup.
-
-## Troubleshooting
-
-### Common Issues
-
-**Configuration Error**: Check that all required credentials are set
-**Signature Validation Failed**: Verify app_secret matches your WhatsApp app
-**Timeout Issues**: Consider using background mode for high-volume applications
-
-### Debug Mode
-
-Enable debug logging in development:
-
-```ruby
-# config/environments/development.rb
-config.log_level = :debug
-``` 

data/examples/whatsapp_message_job.rb

@@ -1,113 +0,0 @@
-# Example Background Jobs for WhatsApp Response Delivery
-# Add these to your Rails application
-
-# Example: Basic WhatsApp Send Job
-# Only handles sending responses - flows are processed synchronously in the controller
-class WhatsappMessageJob < ApplicationJob
-  include FlowChat::Whatsapp::SendJobSupport
-
-  def perform(send_data)
-    perform_whatsapp_send(send_data)
-  end
-end
-
-# Example: Advanced WhatsApp Send Job with custom callbacks
-class AdvancedWhatsappMessageJob < ApplicationJob
-  include FlowChat::Whatsapp::SendJobSupport
-
-  queue_as :whatsapp_priority
-  retry_on StandardError, wait: 2.seconds, attempts: 3
-
-  def perform(send_data)
-    perform_whatsapp_send(send_data)
-  end
-
-  private
-
-  # Override for custom success handling
-  def on_whatsapp_send_success(send_data, result)
-    Rails.logger.info "Successfully sent WhatsApp message to #{send_data[:msisdn]}"
-    UserEngagementTracker.track_message_sent(phone: send_data[:msisdn])
-  end
-
-  # Override for custom error handling
-  def on_whatsapp_send_error(error, send_data)
-    ErrorTracker.notify(error, user_phone: send_data[:msisdn])
-  end
-end
-
-# Example: Priority send job for urgent messages
-class UrgentWhatsappSendJob < ApplicationJob
-  include FlowChat::Whatsapp::SendJobSupport
-
-  queue_as :urgent_whatsapp  # Different queue for priority
-  retry_on StandardError, wait: 1.second, attempts: 5  # Override retry policy
-
-  def perform(send_data)
-    perform_whatsapp_send(send_data)
-  end
-
-  private
-
-  # Override error handling for urgent messages
-  def handle_whatsapp_send_error(error, send_data, config = nil)
-    # Immediately escalate urgent message failures
-    AlertingService.send_urgent_alert(
-      "Urgent WhatsApp send job failed",
-      error: error.message,
-      user: send_data[:msisdn]
-    )
-
-    # Still send user notification
-    super
-  end
-end
-
-# Example: Multi-tenant send job
-class MultiTenantWhatsappSendJob < ApplicationJob
-  include FlowChat::Whatsapp::SendJobSupport
-
-  def perform(send_data)
-    perform_whatsapp_send(send_data)
-  end
-
-  private
-
-  # Override config resolution for tenant-specific configs
-  def resolve_whatsapp_config(send_data)
-    # Use tenant-specific config if available
-    tenant_name = extract_tenant_from_phone(send_data[:msisdn])
-    if tenant_name && FlowChat::Whatsapp::Configuration.exists?(tenant_name)
-      return FlowChat::Whatsapp::Configuration.get(tenant_name)
-    end
-
-    # Fallback to default
-    super
-  end
-
-  def extract_tenant_from_phone(phone)
-    case phone
-    when /^\+1800/
-      :enterprise
-    when /^\+1888/
-      :premium
-    else
-      :standard
-    end
-  end
-end
-
-# Usage in Rails configuration
-#
-# Add to config/application.rb:
-# config.active_job.queue_adapter = :sidekiq
-#
-# Add to config/initializers/flowchat.rb:
-# FlowChat::Config.whatsapp.message_handling_mode = :background
-# FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
-#
-# How it works:
-# 1. Controller receives WhatsApp webhook
-# 2. Flow is processed synchronously (maintains controller context)
-# 3. Response is queued for async delivery via background job
-# 4. Job only handles sending the response, not processing flows