flow_chat 0.8.1 → 0.9.0

data/examples/custom_session_id_example.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+# Example: Custom Session ID Configuration with Proc
+#
+# This example demonstrates how to use a custom proc for session ID generation
+# in FlowChat applications. The proc allows complete customization of how
+# session IDs are generated based on context data.
+
+require "flow_chat"
+
+class CustomSessionIdController < ApplicationController
+  def ussd_endpoint
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Ussd::Gateway::Nalo
+      config.use_session_store FlowChat::Session::CacheSessionStore
+
+      # Example 1: Custom session ID using block/proc
+      config.use_session_config do |context|
+        # Create a custom session ID based on your business logic
+        user_phone = context["request.msisdn"]
+        flow_name = context["flow.name"]
+        gateway = context["request.gateway"]
+        timestamp = Time.current.strftime("%Y%m%d")
+
+        # Custom format: flow_gateway_date_hashedphone
+        "#{flow_name}_#{gateway}_#{timestamp}_#{hash_phone(user_phone)}"
+      end
+    end
+
+    processor.run(SurveyFlow, :main_menu)
+  end
+
+  def whatsapp_endpoint
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+
+      # Example 2: Multi-tenant session IDs
+      config.use_session_config do |context|
+        tenant_id = extract_tenant_from_request(context)
+        user_id = context["request.user_id"] || context["request.msisdn"]
+        flow_name = context["flow.name"]
+
+        "tenant_#{tenant_id}_flow_#{flow_name}_user_#{hash_identifier(user_id)}"
+      end
+    end
+
+    processor.run(CustomerSupportFlow, :handle_inquiry)
+  end
+
+  def http_endpoint
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Http::Gateway::Simple
+      config.use_session_store FlowChat::Session::CacheSessionStore
+
+      # Example 3: API session with custom expiration tracking
+      config.use_session_config do |context|
+        api_key = context.controller.request.headers["X-API-Key"]
+        request_id = context["request.id"]
+
+        # Include API key hash for session isolation per API client
+        "api_#{hash_identifier(api_key)}_req_#{request_id}"
+      end
+    end
+
+    processor.run(ApiFlow, :handle_request)
+  end
+
+  private
+
+  def hash_phone(phone)
+    require "digest"
+    Digest::SHA256.hexdigest(phone)[0, 8]
+  end
+
+  def hash_identifier(identifier)
+    require "digest"
+    Digest::SHA256.hexdigest(identifier.to_s)[0, 8]
+  end
+
+  def extract_tenant_from_request(context)
+    # Extract tenant from subdomain or header
+    request = context.controller&.request
+    return "default" unless request
+
+    host = request.host
+    subdomain = host.split(".").first
+    subdomain if subdomain != "www"
+  end
+end
+
+# Example flows for demonstration
+class SurveyFlow < FlowChat::Flow
+  def main_menu
+    app.screen(:menu) { |p| p.ask "Welcome! Choose an option:", choices: ["Survey", "Exit"] }
+  end
+end
+
+class CustomerSupportFlow < FlowChat::Flow
+  def handle_inquiry
+    app.screen(:inquiry) { |p| p.ask "How can we help you today?" }
+  end
+end
+
+class ApiFlow < FlowChat::Flow
+  def handle_request
+    app.screen(:request) { |p| p.ask "API request received. Provide data:" }
+  end
+end
+
+# Note: The custom session ID proc approach provides:
+# - Complete control over session ID format
+# - Access to full context (request data, flow info, etc.)
+# - Ability to implement complex business logic
+# - Support for multi-tenancy, API authentication, etc.
+#
+# The proc should return a string that will be used as the session ID.
+# Make sure the returned ID is unique for your use case to avoid
+# session collisions.

data/examples/http_controller.rb

@@ -0,0 +1,154 @@
+# Example HTTP Controller for FlowChat HTTP Gateway
+#
+# This controller demonstrates how to use FlowChat with HTTP requests
+# for simple JSON-based conversational interfaces.
+#
+# Usage:
+#   POST /http/webhook
+#   Content-Type: application/json
+#
+#   {
+#     "session_id": "unique_session_123",
+#     "user_id": "user_456",
+#     "input": "Hello"
+#   }
+#
+# Response:
+#   {
+#     "type": "prompt",
+#     "session_id": "unique_session_123",
+#     "user_id": "user_456",
+#     "timestamp": "2024-01-01T12:00:00Z",
+#     "message": "Hello! What's your name?",
+#     "choices": [
+#       {"key": "1", "text": "Continue"}
+#     ]
+#   }
+
+class HttpController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Http::Gateway::Simple
+      config.use_session_store FlowChat::Session::CacheSessionStore
+
+      # Configure session management
+      config.use_session_config(
+        boundaries: [:flow, :platform],
+        hash_identifiers: true,
+        identifier: :msisdn  # Use phone number for durable sessions
+      )
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+
+# Example flow for HTTP gateway
+class WelcomeFlow < FlowChat::Flow
+  def main_page
+    name = app.screen(:name) do |prompt|
+      prompt.ask "Hello! What's your name?",
+        validate: ->(input) { "Name is required" if input.blank? },
+        transform: ->(input) { input.strip.titleize }
+    end
+
+    age = app.screen(:age) do |prompt|
+      prompt.ask "Nice to meet you, #{name}! How old are you?",
+        validate: ->(input) {
+          return "Please enter a number" unless input.match?(/^\d+$/)
+          return "Age must be between 1 and 120" unless (1..120).cover?(input.to_i)
+          nil
+        },
+        transform: ->(input) { input.to_i }
+    end
+
+    preferences = app.screen(:preferences) do |prompt|
+      prompt.select "What are you interested in?", {
+        "tech" => "Technology",
+        "sports" => "Sports",
+        "music" => "Music",
+        "travel" => "Travel"
+      }
+    end
+
+    # Summary
+    app.say "Great! Here's what I learned about you:"
+    app.say "Name: #{name}"
+    app.say "Age: #{age}"
+    app.say "Interest: #{preferences.capitalize}"
+
+    # Ask if they want to continue
+    continue = app.screen(:continue) do |prompt|
+      prompt.yes? "Would you like to explore more features?"
+    end
+
+    if continue
+      features_demo
+    else
+      app.say "Thanks for trying FlowChat HTTP Gateway! 👋"
+    end
+  end
+
+  private
+
+  def features_demo
+    choice = app.screen(:feature_choice) do |prompt|
+      prompt.select "What would you like to try?", {
+        "media" => "Media Support",
+        "validation" => "Input Validation",
+        "session" => "Session Management"
+      }
+    end
+
+    case choice
+    when "media"
+      media_demo
+    when "validation"
+      validation_demo
+    when "session"
+      session_demo
+    end
+  end
+
+  def media_demo
+    app.say "FlowChat supports rich media in HTTP responses!",
+      media: {
+        url: "https://via.placeholder.com/300x200.png?text=FlowChat+HTTP",
+        type: :image,
+        caption: "FlowChat HTTP Gateway Demo"
+      }
+
+    app.say "Media is returned in the JSON response for your frontend to display."
+  end
+
+  def validation_demo
+    email = app.screen(:email) do |prompt|
+      prompt.ask "Enter your email address:",
+        validate: ->(input) {
+          return "Email is required" if input.blank?
+          return "Invalid email format" unless input.match?(/\A[\w+\-.]+@[a-z\d-]+(\.[a-z\d-]+)*\.[a-z]+\z/i)
+          nil
+        },
+        transform: ->(input) { input.downcase.strip }
+    end
+
+    app.say "Perfect! Your email #{email} has been validated and normalized."
+  end
+
+  def session_demo
+    # Store some data in session
+    app.session.set("demo_timestamp", Time.current.to_s)
+    app.session.set("demo_counter", (app.session.get("demo_counter") || 0) + 1)
+
+    counter = app.session.get("demo_counter")
+    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"]}"
+  end
+end

data/examples/intercom_configuration_example.rb

@@ -0,0 +1,118 @@
+# Example configuration for using FlowChat with Intercom
+
+# 1. Rails Credentials Configuration (recommended)
+# Run: rails credentials:edit
+# Add to config/credentials.yml.enc:
+
+# intercom:
+#   access_token: "your_intercom_access_token_here"
+#   client_secret: "your_intercom_client_secret_here"  # For webhook signature validation
+#   admin_id: "your_admin_id_here"  # Required - admin ID for sending messages
+#   skip_signature_validation: false  # Set to true for development/testing
+
+# 2. Environment Variables Configuration (alternative)
+# Set these environment variables:
+
+# INTERCOM_ACCESS_TOKEN=your_intercom_access_token_here
+# INTERCOM_CLIENT_SECRET=your_intercom_client_secret_here
+# INTERCOM_ADMIN_ID=your_admin_id_here
+# INTERCOM_SKIP_SIGNATURE_VALIDATION=false
+
+# 3. Named Configuration Example (for multi-tenant apps)
+class MultiTenantIntercomSetup
+  def self.setup_configurations
+    # Main company configuration
+    FlowChat::Intercom::Configuration.new("main") 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|
+      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)
+    end
+  end
+end
+
+# 4. Routes Configuration
+# Add to config/routes.rb:
+
+# Rails.application.routes.draw do
+#   # Intercom webhook endpoint - supports both HEAD (for URL validation) and POST (for events)
+#   match '/intercom/webhook', to: 'intercom#webhook', via: [:head, :post]
+#
+#   # Multiple tenant support (if needed)
+#   match '/intercom/:tenant/webhook', to: 'intercom#webhook', via: [:head, :post]
+# end
+
+# 5. Controller with Named Configuration
+class TenantAwareIntercomController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    # Get tenant-specific configuration
+    tenant = params[:tenant] || "main"
+    FlowChat::Intercom::Configuration.get(tenant)
+
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Intercom::Gateway::IntercomApi, config
+      config.use_session_store FlowChat::Session::CacheSessionStore
+      config.use_session_config(
+        boundaries: [:flow, :url],  # Separate sessions per tenant
+        identifier: :conversation_id
+      )
+    end
+
+    processor.run CustomerSupportFlow, :handle_conversation
+  end
+end
+
+# 6. Intercom Webhook Setup Instructions
+# To set up webhooks in Intercom:
+#
+# 1. Go to your Intercom Developer Hub
+# 2. Navigate to Configure → Webhooks
+# 3. Add your webhook endpoint:
+#    - Endpoint URL: https://yourdomain.com/intercom/webhook (must use HTTPS)
+#    - Intercom will send a HEAD request to validate your URL
+#    - Your app automatically responds with 200 OK
+#
+# 4. Subscribe to webhook topics:
+#    - conversation.user.created (new conversations)
+#    - conversation.user.replied (user replies)
+#
+# 5. Configure signature validation:
+#    - Find your app's Client Secret in Basic Information
+#    - Add this as client_secret in your Rails credentials
+#    - Webhooks are validated using X-Hub-Signature header with SHA1 HMAC
+#
+# 6. Test the webhook:
+#    - Send a test message in Intercom
+#    - Verify your endpoint receives the webhook notification
+#    - 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:
+#
+#   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"]}" }
+#   ```
+#
+# 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.
+#
+# Note: The old bot_user_id configuration is no longer needed.

data/examples/intercom_controller.rb

@@ -0,0 +1,194 @@
+# Example controller showing how to use the Intercom gateway
+# This controller handles webhooks from Intercom for conversation events
+
+class IntercomController < ApplicationController
+  skip_forgery_protection
+
+  # POST /intercom/webhook
+  # Handle Intercom webhook notifications for conversation events
+  def webhook
+    processor = FlowChat::Processor.new(self) do |config|
+      # Use Intercom gateway with automatic configuration loading
+      config.use_gateway FlowChat::Intercom::Gateway::IntercomApi
+
+      # 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
+      )
+    end
+
+    # Run the customer support flow
+    processor.run CustomerSupportFlow, :handle_conversation
+  end
+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
+    inquiry = app.screen(:inquiry) do |prompt|
+      prompt.ask greeting
+    end
+
+    # Categorize the inquiry and provide appropriate response
+    category = categorize_inquiry(inquiry)
+
+    case category
+    when :technical_support
+      handle_technical_support
+    when :billing
+      handle_billing_inquiry
+    when :general
+      handle_general_inquiry
+    when :escalate
+      escalate_to_human("Complex issue requiring human attention")
+    else
+      app.say "I understand you need help. Let me connect you with one of our team members who can assist you better."
+      escalate_to_human("Unrecognized inquiry type")
+    end
+  end
+
+  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
+    text = inquiry.downcase
+
+    if text.include?("bug") || text.include?("error") || text.include?("not working")
+      :technical_support
+    elsif text.include?("bill") || text.include?("payment") || text.include?("refund")
+      :billing
+    elsif text.include?("urgent") || text.include?("important") || text.include?("asap")
+      :escalate
+    else
+      :general
+    end
+  end
+
+  def handle_technical_support
+    solution = app.screen(:tech_solution) do |prompt|
+      prompt.select "I can help you with technical issues! What type of problem are you experiencing?", {
+        "login" => "Can't log in",
+        "performance" => "App is slow",
+        "features" => "Feature not working",
+        "other" => "Something else"
+      }
+    end
+
+    case solution
+    when "login"
+      provide_login_help
+    when "performance"
+      provide_performance_tips
+    when "features"
+      provide_feature_help
+    when "other"
+      escalate_to_human("Technical issue requiring human review")
+    end
+  end
+
+  def handle_billing_inquiry
+    app.say "For billing questions, I'm connecting you with our billing team who can access your account securely."
+    escalate_to_human("Billing inquiry", team_id: "billing_team_id")
+  end
+
+  def handle_general_inquiry
+    satisfaction = app.screen(:satisfaction) do |prompt|
+      prompt.select "I hope I was able to help! How would you rate your experience?", {
+        "1" => "😞 Poor",
+        "2" => "😐 Okay",
+        "3" => "😊 Good",
+        "4" => "😍 Excellent"
+      }
+    end
+
+    if satisfaction.to_i >= 3
+      app.say "Thank you for the positive feedback! Feel free to reach out if you need anything else."
+    else
+      app.say "I'm sorry the experience wasn't better. Let me connect you with a team member who can help."
+      escalate_to_human("User reported poor experience")
+    end
+  end
+
+  def provide_login_help
+    app.say <<~MESSAGE
+      Here are some steps to try for login issues:
+      
+      1. Make sure you're using the correct email address
+      2. Try resetting your password using the "Forgot Password" link
+      3. Clear your browser cache and cookies
+      4. Try logging in from an incognito/private window
+      
+      If none of these work, I'll connect you with our technical support team.
+    MESSAGE
+
+    still_stuck = app.screen(:login_resolved) do |prompt|
+      prompt.yes? "Did these steps help resolve your login issue?"
+    end
+
+    unless still_stuck
+      escalate_to_human("Login issue not resolved by self-service steps")
+    end
+  end
+
+  def provide_performance_tips
+    app.say <<~MESSAGE
+      Here are some tips to improve app performance:
+      
+      1. Close other browser tabs or apps
+      2. Check your internet connection
+      3. Try refreshing the page
+      4. Update your browser to the latest version
+      
+      If the problem persists, our technical team can investigate further.
+    MESSAGE
+  end
+
+  def provide_feature_help
+    feature = app.screen(:which_feature) do |prompt|
+      prompt.ask "Which feature are you having trouble with? Please describe what you're trying to do."
+    end
+
+    app.say "Thanks for the details about #{feature}. Let me connect you with our product team who can provide specific guidance."
+    escalate_to_human("Feature support request: #{feature}")
+  end
+
+  def escalate_to_human(reason, team_id: nil)
+    conversation_id = app.context["request.conversation_id"]
+
+    # Business logic: Use Intercom manager for conversation control
+    if app.gateway == :intercom_api
+      # Access the gateway's client and manager for escalation
+      # This would be implemented by exposing these through the gateway
+      app.say "I'm connecting you with one of our team members who can provide more personalized assistance. They'll be with you shortly!"
+
+      # Business logic would handle:
+      # - Remove AI_HANDLING tag
+      # - Add ESCALATED tag
+      # - Assign to appropriate team
+      # - Set priority based on reason
+      # - Add internal note for context
+
+      FlowChat.logger.info { "CustomerSupportFlow: Escalating conversation #{conversation_id} - Reason: #{reason}" }
+    else
+      app.say "Let me transfer you to a human agent who can help you further."
+    end
+  end
+end

data/examples/multi_tenant_whatsapp_controller.rb

@@ -9,7 +9,7 @@ class MultiTenantWhatsappController < ApplicationController
     tenant = determine_tenant(request)
     whatsapp_config = get_whatsapp_config_for_tenant(tenant)
 
-    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: !Rails.env.production?) do |config|
+    processor = FlowChat::Processor.new(self, enable_simulator: !Rails.env.production?) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, whatsapp_config
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
@@ -96,7 +96,7 @@ class DatabaseWhatsappController < ApplicationController
       config.app_secret = business_account.whatsapp_app_secret
     end
 
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+    processor = FlowChat::Processor.new(self) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, whatsapp_config
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
@@ -135,7 +135,7 @@ class EnvironmentWhatsappController < ApplicationController
       FlowChat::Whatsapp::Configuration.from_credentials
     end
 
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+    processor = FlowChat::Processor.new(self) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, whatsapp_config
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
@@ -193,7 +193,7 @@ class CustomWhatsappController < ApplicationController
     my_config.app_secret = "your_app_secret"
     my_config.business_account_id = "your_business_account_id"
 
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+    processor = FlowChat::Processor.new(self) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, my_config
       config.use_session_store FlowChat::Session::CacheSessionStore
     end

data/examples/simulator_controller.rb

@@ -31,6 +31,15 @@ class SimulatorController < ApplicationController
         icon: "💬",
         color: "#25D366"
       },
+      http_main: {
+        name: "Main HTTP API",
+        description: "JSON HTTP API endpoint",
+        processor_type: "http",
+        gateway: "http_simple",
+        endpoint: "/http/webhook",
+        icon: "🌐",
+        color: "#0066cc"
+      },
       whatsapp_tenant_a: {
         name: "Tenant A WhatsApp",
         description: "Multi-tenant endpoint for Tenant A",
@@ -40,6 +49,15 @@ class SimulatorController < ApplicationController
         icon: "🏢",
         color: "#fd7e14"
       },
+      http_external: {
+        name: "External HTTP Test",
+        description: "Test with external HTTP server",
+        processor_type: "http",
+        gateway: "http_simple",
+        endpoint: "http://localhost:4567/http/webhook",
+        icon: "🔗",
+        color: "#17a2b8"
+      },
       whatsapp_legacy: {
         name: "Legacy WhatsApp",
         description: "Legacy endpoint for compatibility",
@@ -54,7 +72,7 @@ class SimulatorController < ApplicationController
 
   # Default configuration to start with
   def default_config_key
-    :whatsapp_main
+    :http_main
   end
 
   # Default test phone number
@@ -79,8 +97,10 @@ end
 # 5. View request/response logs in real-time
 
 # This allows you to test:
+# - Different protocol types (USSD, WhatsApp, HTTP)
 # - Different controller implementations on the same server
 # - Different API versions (v1, v2, etc.)
 # - Multi-tenant endpoints with different configurations
 # - Legacy endpoints alongside new ones
+# - External HTTP servers (run examples/http_simulator_test.rb)
 # - Different flow implementations for different endpoints