flow_chat 0.8.2 → 0.10.0

data/examples/http_controller.rb

@@ -6,10 +6,10 @@
 # Usage:
 #   POST /http/webhook
 #   Content-Type: application/json
-#   
+#
 #   {
 #     "session_id": "unique_session_123",
-#     "user_id": "user_456", 
+#     "user_id": "user_456",
 #     "input": "Hello"
 #   }
 #
@@ -29,24 +29,26 @@ class HttpController < ApplicationController
   skip_forgery_protection
 
   def webhook
-    processor = FlowChat::Http::Processor.new(self) do |config|
+    processor = FlowChat::Processor.new(self) do |config|
       config.use_gateway FlowChat::Http::Gateway::Simple
       config.use_session_store FlowChat::Session::CacheSessionStore
-      
-      # Configure session management
+
+      # The HTTP gateway sets request.user_id from the request's user_id, so key
+      # sessions on it. (:msisdn would be nil here, collapsing every caller into
+      # one session.)
       config.use_session_config(
         boundaries: [:flow, :platform],
         hash_identifiers: true,
-        identifier: :msisdn  # Use phone number for durable sessions
+        identifier: :user_id
       )
     end
 
-    processor.run WelcomeFlow, :main_page
+    processor.run HttpWelcomeFlow, :main_page
   end
 end
 
 # Example flow for HTTP gateway
-class WelcomeFlow < FlowChat::Flow
+class HttpWelcomeFlow < FlowChat::Flow
   def main_page
     name = app.screen(:name) do |prompt|
       prompt.ask "Hello! What's your name?",
@@ -56,9 +58,9 @@ class WelcomeFlow < FlowChat::Flow
 
     age = app.screen(:age) do |prompt|
       prompt.ask "Nice to meet you, #{name}! How old are you?",
-        validate: ->(input) { 
+        validate: ->(input) {
           return "Please enter a number" unless input.match?(/^\d+$/)
-          return "Age must be between 1 and 120" unless (1..120).include?(input.to_i)
+          return "Age must be between 1 and 120" unless (1..120).cover?(input.to_i)
           nil
         },
         transform: ->(input) { input.to_i }
@@ -67,7 +69,7 @@ class WelcomeFlow < FlowChat::Flow
     preferences = app.screen(:preferences) do |prompt|
       prompt.select "What are you interested in?", {
         "tech" => "Technology",
-        "sports" => "Sports", 
+        "sports" => "Sports",
         "music" => "Music",
         "travel" => "Travel"
       }
@@ -78,7 +80,7 @@ class WelcomeFlow < FlowChat::Flow
     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?"
@@ -87,7 +89,7 @@ class WelcomeFlow < FlowChat::Flow
     if continue
       features_demo
     else
-      app.say "Thanks for trying FlowChat HTTP Gateway! 👋"
+      app.say "Thanks for trying the FlowChat HTTP gateway!"
     end
   end
 
@@ -115,7 +117,7 @@ class WelcomeFlow < FlowChat::Flow
   def media_demo
     app.say "FlowChat supports rich media in HTTP responses!",
       media: {
-        url: "https://via.placeholder.com/300x200.png?text=FlowChat+HTTP",
+        url: "https://example.com/images/flowchat-http-demo.png",
         type: :image,
         caption: "FlowChat HTTP Gateway Demo"
       }
@@ -128,7 +130,7 @@ class WelcomeFlow < FlowChat::Flow
       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)
+          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 }
@@ -146,9 +148,9 @@ class WelcomeFlow < FlowChat::Flow
     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']}"
+    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.context["session.id"]}"
   end
-end 
+end

data/examples/intercom_configuration_example.rb

@@ -0,0 +1,113 @@
+# 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
+    # Passing a name registers the configuration under that name, so you can
+    # fetch it later with Configuration.get(:main). Set attributes with tap;
+    # Configuration.new does not yield a block.
+    FlowChat::Intercom::Configuration.new("main").tap 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").tap 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
+    # Fetch the named configuration registered in setup_configurations above.
+    tenant = params[:tenant] || "main"
+    tenant_config = FlowChat::Intercom::Configuration.get(tenant)
+
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Intercom::Gateway::IntercomApi, tenant_config
+      config.use_session_store FlowChat::Session::CacheSessionStore
+      # request.id is the conversation id (the default :request_id identifier),
+      # so each conversation gets its own session. The :url boundary separates
+      # tenants that share the flow.
+      config.use_session_config(boundaries: [:flow, :url])
+    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)
+# The admin_id identifies which admin sends messages to a conversation.
+# FlowChat's own client only sends messages, so list admins with the official
+# intercom gem in a Rails console:
+#
+#   rails console
+#   ```
+#     intercom = Intercom::Client.new(token: Rails.application.credentials.dig(:intercom, :access_token))
+#     intercom.admins.all.each { |admin| puts "#{admin.name} (#{admin.email}) - ID: #{admin.id}" }
+#   ```
+#
+# Copy the ID of the admin you want to send from. You can also find it in the
+# Intercom Developer Hub under your app's Configure -> Basic Information.
+#
+# Note: The old bot_user_id configuration is no longer needed.

data/examples/intercom_controller.rb

@@ -0,0 +1,182 @@
+# 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
+
+      # The Intercom gateway sets request.id to the conversation id, and the
+      # default identifier (:request_id) uses it, so each conversation already
+      # gets its own session. Scope by flow as well.
+      config.use_session_config(boundaries: [:flow])
+    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
+    # Ask the opening question. The prompt is only shown on the first unanswered
+    # turn; once the user replies, screen(:inquiry) returns their stored answer.
+    inquiry = app.screen(:inquiry) do |prompt|
+      prompt.ask "Hello! I'm here to help you. How can I assist you today?"
+    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 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.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