flow_chat 0.8.1 → 0.9.0

data/examples/ussd_controller.rb

@@ -5,10 +5,10 @@ class UssdController < ApplicationController
   skip_forgery_protection
 
   def process_request
-    processor = FlowChat::Ussd::Processor.new(self) do |config|
+    processor = FlowChat::Processor.new(self) do |config|
       config.use_gateway FlowChat::Ussd::Gateway::Nalo
-      # Use Rails session for USSD (shorter sessions)
-      config.use_session_store FlowChat::Session::RailsSessionStore
+      # Use cache session store for USSD
+      config.use_session_store FlowChat::Session::CacheSessionStore
 
       # Enable durable sessions (optional)
       config.use_durable_sessions  # Configures flow+platform isolation with durable sessions
@@ -194,9 +194,9 @@ class UssdController < ApplicationController
     FlowChat::Config.ussd.pagination_next_option = "#"
     FlowChat::Config.ussd.pagination_back_option = "*"
 
-    processor = FlowChat::Ussd::Processor.new(self) do |config|
+    processor = FlowChat::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
@@ -228,16 +228,16 @@ class UssdController < ApplicationController
   skip_forgery_protection
 
   def process_request
-    processor = FlowChat::Ussd::Processor.new(self) do |config|
+    processor = FlowChat::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  # Add custom logging
       config.use_durable_sessions           # Enable durable sessions
-      
+
       # Or configure session boundaries explicitly:
       # config.use_session_config(
       #   boundaries: [:flow, :platform],     # which boundaries to enforce
-      #   hash_phone_numbers: true            # hash phone numbers for privacy
+      #   hash_identifiers: true            # hash phone numbers for privacy
       # )
     end
 
@@ -252,7 +252,7 @@ class UssdController < ApplicationController
   skip_forgery_protection
 
   def process_request
-    processor = FlowChat::Ussd::Processor.new(self) do |config|
+    processor = FlowChat::Processor.new(self) do |config|
       config.use_gateway FlowChat::Ussd::Gateway::Nalo
       # Use cache store for longer session persistence
       config.use_session_store FlowChat::Session::CacheSessionStore

data/examples/whatsapp_controller.rb

@@ -6,7 +6,7 @@ class WhatsappController < ApplicationController
   skip_forgery_protection
 
   def webhook
-    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: Rails.env.development?) do |config|
+    processor = FlowChat::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
@@ -25,7 +25,7 @@ class CustomWhatsappController < ApplicationController
   def webhook
     custom_config = build_whatsapp_config
 
-    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, custom_config
       config.use_session_store FlowChat::Session::CacheSessionStore
     end

data/flow_chat.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
@@ -36,4 +37,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "actionpack", ">= 6"
   spec.add_dependency "phonelib"
   spec.add_dependency "ibsciss-middleware", "~> 0.4.2"
+  spec.add_dependency "intercom", "~> 4.2"
+  spec.add_dependency "reverse_markdown", "~> 3.0"
+  spec.add_dependency "kramdown", "~> 2.4"
 end

data/lib/flow_chat/{base_app.rb → app.rb}

@@ -1,10 +1,9 @@
 module FlowChat
-  class BaseApp
-    attr_reader :session, :input, :context, :navigation_stack
+  class App
+    attr_reader :input, :context, :navigation_stack
 
     def initialize(context)
       @context = context
-      @session = context.session
       @input = context.input
       @navigation_stack = []
     end
@@ -27,11 +26,11 @@ module FlowChat
 
     def go_back
       return false if navigation_stack.empty?
-      
+
       @context.input = nil
       current_screen = navigation_stack.last
       session.delete(current_screen)
-      
+
       # Restart the flow from the beginning
       raise FlowChat::Interrupt::RestartFlow.new
     end
@@ -40,7 +39,19 @@ module FlowChat
       raise FlowChat::Interrupt::Terminate.new(msg, media: media)
     end
 
-    def phone_number
+    def platform
+      context["request.platform"]
+    end
+
+    def gateway
+      context["request.gateway"]
+    end
+
+    def user_id
+      context["request.user_id"]
+    end
+
+    def msisdn
       context["request.msisdn"]
     end
 
@@ -64,11 +75,19 @@ module FlowChat
       nil
     end
 
+    def session
+      @context.session
+    end
+
     protected
 
-    # Platform-specific methods to be overridden
     def prepare_user_input
-      input
+      user_input = input
+      if platform != :ussd && session.get(FlowChat::Input::START).nil?
+        session.set(FlowChat::Input::START, user_input)
+        user_input = nil
+      end
+      user_input
     end
   end
-end 
+end

data/lib/flow_chat/async_job.rb

@@ -0,0 +1,176 @@
+begin
+  require "active_job"
+rescue LoadError
+  # ActiveJob not available - async features will not be available
+end
+require "ostruct"
+
+module FlowChat
+  # Base class for background flow processing jobs
+  # Users inherit from this and implement execute(controller, **job_params)
+  if defined?(ActiveJob::Base)
+    class AsyncJob < ActiveJob::Base
+      queue_as :default
+
+      def perform(request_context:, **job_params)
+        FlowChat.logger.debug { "AsyncJob: Starting background job with params: #{job_params.inspect}" }
+
+        # Create BackgroundController from serialized request
+        controller = BackgroundController.new(request_context)
+
+        # User implements execute and calls processor.run themselves
+        # Pass job_params as keyword arguments to execute
+        execute(controller, **job_params)
+
+        FlowChat.logger.debug { "AsyncJob: Background job completed successfully" }
+      end
+
+      # Abstract method - user must implement
+      # User builds processor AND calls processor.run themselves
+      # Job params from use_async(JobClass, key: value) are passed as keyword arguments
+      def execute(controller, **job_params)
+        raise NotImplementedError, "Subclasses must implement #execute(controller, **job_params)"
+      end
+    end
+  else
+    # Fallback when ActiveJob is not available
+    class AsyncJob
+      def perform(request_context:, **job_params)
+        FlowChat.logger.debug { "AsyncJob: Starting background job with params: #{job_params.inspect}" }
+
+        # Create BackgroundController from serialized request
+        controller = BackgroundController.new(request_context)
+
+        # User implements execute and calls processor.run themselves
+        # Pass job_params as keyword arguments to execute
+        execute(controller, **job_params)
+
+        FlowChat.logger.debug { "AsyncJob: Background job completed successfully" }
+      end
+
+      # Abstract method - user must implement
+      # User builds processor AND calls processor.run themselves
+      # Job params from use_async(JobClass, key: value) are passed as keyword arguments
+      def execute(controller, **job_params)
+        raise NotImplementedError, "Subclasses must implement #execute(controller, **job_params)"
+      end
+
+      # Stub perform_later for testing when ActiveJob is not available
+      def self.perform_later(args)
+        new.perform(**args)
+      end
+    end
+  end
+
+  # Duck-type controller for background jobs
+  # Provides render/head no-ops and request interface
+  class BackgroundController
+    attr_reader :request, :response
+
+    def initialize(request_data)
+      FlowChat.logger.debug { "BackgroundController: Initializing with request data" }
+      @request = BackgroundRequest.new(request_data)
+      @response = nil
+    end
+
+    # Delegate params to request (mimics Rails controller behavior)
+    def params
+      request.params
+    end
+
+    def render(options)
+      FlowChat.logger.debug { "BackgroundController: render called (no-op): #{options.inspect}" }
+      @response = options
+      nil  # No-op in background
+    end
+
+    def head(status)
+      FlowChat.logger.debug { "BackgroundController: head called (no-op): #{status}" }
+      @response = {status: status}
+      nil  # No-op in background
+    end
+
+    def is_a?(klass)
+      return true if klass == FlowChat::BackgroundController
+      super
+    end
+
+    def kind_of?(klass)
+      return true if klass == FlowChat::BackgroundController
+      super
+    end
+  end
+
+  # Request object for background jobs
+  # Reconstructed from serialized webhook request data
+  class BackgroundRequest
+    attr_reader :params, :method, :headers, :host, :path, :remote_ip
+
+    def initialize(request_data)
+      @params = (request_data[:params] || {}).with_indifferent_access
+      @method = request_data[:method] || "POST"
+      @headers = OpenStruct.new(request_data[:headers] || {})
+      @host = request_data[:host]
+      @path = request_data[:path]
+      @body_content = request_data[:body]
+      @remote_ip = request_data[:remote_ip]
+
+      FlowChat.logger.debug { "BackgroundRequest: Initialized with method=#{@method}, params keys=#{@params.keys.inspect}" }
+    end
+
+    # Rails request interface compatibility
+    def request_method
+      method.upcase
+    end
+
+    def user_agent
+      @headers["User-Agent"]
+    end
+
+    def ssl?
+      # Background jobs don't have SSL context
+      false
+    end
+
+    def post?
+      method.upcase == "POST"
+    end
+
+    def get?
+      method.upcase == "GET"
+    end
+
+    def head?
+      method.upcase == "HEAD"
+    end
+
+    def body
+      # Return StringIO-like object if body content exists
+      @body_content ? BackgroundRequestBody.new(@body_content) : nil
+    end
+
+    def cookies
+      # Background jobs don't have cookies
+      {}
+    end
+  end
+
+  # Body wrapper for BackgroundRequest
+  # Provides read() method that Rails expects
+  class BackgroundRequestBody
+    def initialize(content)
+      @content = content
+      @read = false
+    end
+
+    def read
+      return "" if @read
+      @read = true
+      @content
+    end
+
+    def rewind
+      @read = false
+    end
+  end
+end

data/lib/flow_chat/config.rb

@@ -7,6 +7,8 @@ module FlowChat
     # When true (default), validation errors are combined with the original message.
     # When false, only the validation error message is shown to the user.
     mattr_accessor :combine_validation_error_with_message, default: true
+    # When true, inject logger into middleware stack. Defaults to true in Rails development.
+    mattr_accessor :inject_middleware_logger, default: defined?(Rails) && Rails.env.development?
 
     # Session configuration object
     def self.session
@@ -23,8 +25,13 @@ module FlowChat
       @whatsapp ||= WhatsappConfig.new
     end
 
+    # HTTP-specific configuration object
+    def self.http
+      @http ||= HttpConfig.new
+    end
+
     class SessionConfig
-      attr_accessor :boundaries, :hash_phone_numbers, :identifier
+      attr_accessor :boundaries, :hash_identifiers, :identifier, :session_id_proc
 
       def initialize
         # Session boundaries control how session IDs are constructed
@@ -32,14 +39,17 @@ module FlowChat
         # :gateway = separate sessions per gateway
         # :platform = separate sessions per platform (ussd, whatsapp)
         @boundaries = [:flow, :gateway, :platform]
-        
+
         # Always hash phone numbers for privacy
-        @hash_phone_numbers = true
-        
+        @hash_identifiers = true
+
         # Session identifier type (nil = let platforms choose their default)
         # :msisdn = durable sessions (durable across timeouts)
         # :request_id = ephemeral sessions (new session each time)
         @identifier = nil
+
+        # Proc for custom session ID generation (overrides default behavior when set)
+        @session_id_proc = nil
       end
     end
 
@@ -57,35 +67,20 @@ module FlowChat
     end
 
     class WhatsappConfig
-      attr_accessor :background_job_class
-      attr_reader :message_handling_mode, :api_base_url
+      attr_reader :api_base_url
 
       def initialize
-        @message_handling_mode = :inline
-        @background_job_class = "WhatsappMessageJob"
-        @api_base_url = "https://graph.facebook.com/v22.0"
-      end
-
-      # Validate message handling mode
-      def message_handling_mode=(mode)
-        valid_modes = [:inline, :background, :simulator]
-        unless valid_modes.include?(mode.to_sym)
-          raise ArgumentError, "Invalid message handling mode: #{mode}. Valid modes: #{valid_modes.join(", ")}"
-        end
-        @message_handling_mode = mode.to_sym
-      end
-
-      # Helper methods for mode checking
-      def inline_mode?
-        @message_handling_mode == :inline
+        @api_base_url = "https://graph.facebook.com/v23.0"
       end
+    end
 
-      def background_mode?
-        @message_handling_mode == :background
-      end
+    class HttpConfig
+      attr_accessor :default_gateway, :request_timeout, :response_format
 
-      def simulator_mode?
-        @message_handling_mode == :simulator
+      def initialize
+        @default_gateway = :simple
+        @request_timeout = 30
+        @response_format = :json
       end
     end
   end

data/lib/flow_chat/{base_executor.rb → executor.rb}

@@ -1,8 +1,8 @@
 module FlowChat
-  class BaseExecutor
+  class Executor
     def initialize(app)
       @app = app
-      FlowChat.logger.debug { "#{log_prefix}: Initialized #{platform_name} executor middleware" }
+      FlowChat.logger.debug { "#{log_prefix}: Initialized executor middleware" }
     end
 
     def call(context)
@@ -13,7 +13,7 @@ module FlowChat
       FlowChat.logger.info { "#{log_prefix}: Executing flow #{flow_class.name}##{action} for session #{session_id}" }
 
       platform_app = build_platform_app(context)
-      FlowChat.logger.debug { "#{log_prefix}: #{platform_name} app built for flow execution" }
+      FlowChat.logger.debug { "#{log_prefix}: app built for flow execution" }
 
       flow = flow_class.new platform_app
       FlowChat.logger.debug { "#{log_prefix}: Flow instance created, invoking #{action} method" }
@@ -32,7 +32,7 @@ module FlowChat
       FlowChat.logger.info { "#{log_prefix}: Flow terminated - Session: #{session_id}, Message: '#{e.prompt&.truncate(100)}'" }
       FlowChat.logger.debug { "#{log_prefix}: Destroying session #{session_id}" }
       context.session.destroy
-      [:terminate, e.prompt, nil, e.media]
+      [:terminal, e.prompt, nil, e.media]
     rescue => error
       FlowChat.logger.error { "#{log_prefix}: Flow execution failed - #{flow_class.name}##{action}, Session: #{session_id}, Error: #{error.class.name}: #{error.message}" }
       FlowChat.logger.debug { "#{log_prefix}: Stack trace: #{error.backtrace.join("\n")}" }
@@ -41,17 +41,12 @@ module FlowChat
 
     protected
 
-    # Subclasses must implement these methods
-    def platform_name
-      raise NotImplementedError, "Subclasses must implement platform_name"
-    end
-
     def log_prefix
-      raise NotImplementedError, "Subclasses must implement log_prefix"
+      "Executor"
     end
 
     def build_platform_app(context)
-      raise NotImplementedError, "Subclasses must implement build_platform_app"
+      FlowChat::App.new(context)
     end
   end
-end 
+end

data/lib/flow_chat/factory.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module FlowChat
+  # Factory provides centralized processor configuration for consistent setup across
+  # webhook and background contexts.
+  #
+  # Example:
+  #   # In config/initializers/flow_chat.rb
+  #   FlowChat::Factory.register :whatsapp do |controller|
+  #     processor = FlowChat::Processor.new(controller) do |config|
+  #       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+  #       config.use_session_store FlowChat::Session::CacheSessionStore
+  #       config.use_session_config(boundaries: [:flow])
+  #       config.use_async(WhatsAppFlowJob)
+  #     end
+  #     processor.run(WhatsAppFlow, :start)
+  #   end
+  #
+  #   # In webhook controller
+  #   FlowChat::Factory.execute(:whatsapp, controller: self)
+  #
+  #   # In background job
+  #   FlowChat::Factory.execute(:whatsapp, controller: controller)
+  class Factory
+    class << self
+      # Register a processor factory with a given name
+      #
+      # @param name [Symbol] The factory name (e.g., :whatsapp, :intercom)
+      # @param block [Proc] The factory block that receives controller
+      # @return [void]
+      #
+      # @example
+      #   FlowChat::Factory.register :whatsapp do |controller|
+      #     processor = FlowChat::Processor.new(controller) do |config|
+      #       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      #     end
+      #     processor.run(WhatsAppFlow, :start)
+      #   end
+      def register(name, &block)
+        FlowChat.logger.debug { "Factory: Registering factory '#{name}'" }
+        factories[name] = block
+      end
+
+      # Execute a registered factory
+      #
+      # @param name [Symbol] The factory name
+      # @param controller [Object] The controller instance (webhook or background)
+      # @return [void]
+      # @raise [FactoryNotFoundError] If factory is not registered
+      #
+      # @example
+      #   FlowChat::Factory.execute(:whatsapp, controller: self)
+      def execute(name, controller:)
+        factory = factories[name]
+        raise FactoryNotFoundError, "Factory '#{name}' not registered" unless factory
+
+        FlowChat.logger.debug { "Factory: Executing factory '#{name}'" }
+        factory.call(controller)
+      end
+
+      # Check if a factory is registered
+      #
+      # @param name [Symbol] The factory name
+      # @return [Boolean]
+      def registered?(name)
+        factories.key?(name)
+      end
+
+      # Get all registered factory names
+      #
+      # @return [Array<Symbol>]
+      def registered_factories
+        factories.keys
+      end
+
+      # Clear all registered factories (primarily for testing)
+      #
+      # @return [void]
+      def clear!
+        FlowChat.logger.debug { "Factory: Clearing all registered factories" }
+        factories.clear
+      end
+
+      private
+
+      def factories
+        @factories ||= {}
+      end
+    end
+
+    # Error raised when attempting to execute an unregistered factory
+    class FactoryNotFoundError < StandardError; end
+  end
+end

data/lib/flow_chat/gateway_async_support.rb

@@ -0,0 +1,106 @@
+require_relative "async_job"
+
+module FlowChat
+  # Concern for gateways to support async background processing
+  # Mix this into gateway classes to enable async detection and job enqueueing
+  module GatewayAsyncSupport
+    attr_reader :controller, :context
+
+    # Check if gateway supports async processing
+    # Override in gateways that don't support async (e.g., USSD)
+    def async_supported?
+      true
+    end
+
+    # Detect if we're currently in background mode
+    def in_background?
+      @controller.is_a?(::FlowChat::BackgroundController)
+    end
+
+    # Check if async processing should be used
+    # Returns true if:
+    # - Not already in background mode
+    # - Processor has async enabled
+    # - Gateway supports async
+    def should_enqueue_async?
+      processor = @context["processor"]
+
+      !in_background? &&
+        processor&.async_enabled? &&
+        async_supported?
+    end
+
+    # Enqueue background job with serialized request context
+    # Returns true if job was enqueued, false otherwise
+    def enqueue_async_job
+      return false unless should_enqueue_async?
+
+      processor = @context["processor"]
+
+      FlowChat.logger.info { "#{self.class.name}: Async enabled - enqueuing background job" }
+
+      # Serialize request data for BackgroundController
+      request_data = {
+        params: @controller.request.params.to_h,
+        method: @controller.request.method,
+        headers: extract_headers_for_background(@controller.request),
+        host: extract_host(@controller.request),
+        path: extract_path(@controller.request),
+        body: extract_body_for_background(@controller.request),
+        remote_ip: extract_remote_ip(@controller.request)
+      }
+
+      # Enqueue user's job with request context and job params
+      processor.async_job_class.perform_later(
+        request_context: request_data,
+        **processor.async_job_params
+      )
+
+      FlowChat.logger.info { "#{self.class.name}: Background job enqueued successfully" }
+
+      true
+    end
+
+    # Extract serializable headers needed for background processing
+    # Override in gateways that need additional headers
+    def extract_headers_for_background(request)
+      {
+        "Content-Type" => request.headers["Content-Type"],
+        "User-Agent" => request.headers["User-Agent"]
+      }.compact
+    end
+
+    # Extract host from request for URL boundary support
+    def extract_host(request)
+      request.host
+    rescue
+      nil
+    end
+
+    # Extract path from request for URL boundary support
+    def extract_path(request)
+      request.path
+    rescue
+      nil
+    end
+
+    # Extract request body for background processing
+    # Override in gateways that need the request body
+    def extract_body_for_background(request)
+      return nil unless request.body
+
+      body_content = request.body.read
+      request.body.rewind  # Reset for subsequent reads
+      body_content
+    rescue
+      nil
+    end
+
+    # Extract remote IP from request
+    def extract_remote_ip(request)
+      request.remote_ip
+    rescue
+      nil
+    end
+  end
+end