flow_chat 0.6.1 → 0.8.0

data/lib/flow_chat/whatsapp/middleware/executor.rb

@@ -4,24 +4,46 @@ module FlowChat
       class Executor
         def initialize(app)
           @app = app
+          FlowChat.logger.debug { "Whatsapp::Executor: Initialized WhatsApp executor middleware" }
         end
 
         def call(context)
+          flow_class = context.flow
+          action = context["flow.action"]
+          session_id = context["session.id"]
+
+          FlowChat.logger.info { "Whatsapp::Executor: Executing flow #{flow_class.name}##{action} for session #{session_id}" }
+
           whatsapp_app = build_whatsapp_app context
-          flow = context.flow.new whatsapp_app
-          flow.send context["flow.action"]
+          FlowChat.logger.debug { "Whatsapp::Executor: WhatsApp app built for flow execution" }
+
+          flow = flow_class.new whatsapp_app
+          FlowChat.logger.debug { "Whatsapp::Executor: Flow instance created, invoking #{action} method" }
+
+          flow.send action
+          FlowChat.logger.warn { "Whatsapp::Executor: Flow execution failed to interact with user for #{flow_class.name}##{action}" }
+          raise FlowChat::Interrupt::Terminate, "Unexpected end of flow."
         rescue FlowChat::Interrupt::Prompt => e
+          FlowChat.logger.info { "Whatsapp::Executor: Flow prompted user - Session: #{session_id}, Prompt: '#{e.prompt.truncate(100)}'" }
+          FlowChat.logger.debug { "Whatsapp::Executor: Prompt details - Choices: #{e.choices&.size || 0}, Has media: #{!e.media.nil?}" }
           # Return the same triplet format as USSD for consistency
           [:prompt, e.prompt, e.choices, e.media]
         rescue FlowChat::Interrupt::Terminate => e
+          FlowChat.logger.info { "Whatsapp::Executor: Flow terminated - Session: #{session_id}, Message: '#{e.prompt.truncate(100)}'" }
+          FlowChat.logger.debug { "Whatsapp::Executor: Destroying session #{session_id}" }
           # Clean up session and return terminal message
           context.session.destroy
           [:terminate, e.prompt, nil, e.media]
+        rescue => error
+          FlowChat.logger.error { "Whatsapp::Executor: Flow execution failed - #{flow_class.name}##{action}, Session: #{session_id}, Error: #{error.class.name}: #{error.message}" }
+          FlowChat.logger.debug { "Whatsapp::Executor: Stack trace: #{error.backtrace.join("\n")}" }
+          raise
         end
 
         private
 
         def build_whatsapp_app(context)
+          FlowChat.logger.debug { "Whatsapp::Executor: Building WhatsApp app instance" }
           FlowChat::Whatsapp::App.new(context)
         end
       end

data/lib/flow_chat/whatsapp/processor.rb

@@ -2,6 +2,7 @@ module FlowChat
   module Whatsapp
     class Processor < FlowChat::BaseProcessor
       def use_whatsapp_config(config)
+        FlowChat.logger.debug { "Whatsapp::Processor: Configuring WhatsApp config: #{config.class.name}" }
         @whatsapp_config = config
         self
       end
@@ -13,13 +14,18 @@ module FlowChat
       end
 
       def build_middleware_stack
+        FlowChat.logger.debug { "Whatsapp::Processor: Building WhatsApp middleware stack" }
         create_middleware_stack("whatsapp")
       end
 
       def configure_middleware_stack(builder)
-        builder.use FlowChat::Session::Middleware
+        FlowChat.logger.debug { "Whatsapp::Processor: Configuring WhatsApp middleware stack" }
+
         builder.use middleware
+        FlowChat.logger.debug { "Whatsapp::Processor: Added custom middleware" }
+
         builder.use FlowChat::Whatsapp::Middleware::Executor
+        FlowChat.logger.debug { "Whatsapp::Processor: Added Whatsapp::Middleware::Executor" }
       end
     end
   end

data/lib/flow_chat/whatsapp/renderer.rb

@@ -49,15 +49,10 @@ module FlowChat
       end
 
       def build_selection_message
-        # Determine the best way to present choices
-        if choices.is_a?(Array)
-          # Convert array to hash with index-based keys
-          choice_hash = choices.each_with_index.to_h { |choice, index| [index.to_s, choice] }
-          build_interactive_message(choice_hash)
-        elsif choices.is_a?(Hash)
+        if choices.is_a?(Hash)
           build_interactive_message(choices)
         else
-          raise ArgumentError, "choices must be an Array or Hash"
+          raise ArgumentError, "choices must be a Hash"
         end
       end
 
@@ -121,7 +116,7 @@ module FlowChat
           }
         when :video
           {
-            type: "video", 
+            type: "video",
             video: {link: url}
           }
         when :document
@@ -188,4 +183,4 @@ module FlowChat
       end
     end
   end
-end 
+end

data/lib/flow_chat.rb

@@ -2,6 +2,8 @@ require "zeitwerk"
 require "active_support"
 require "active_support/core_ext/time"
 require "active_support/core_ext/object/blank"
+require "active_support/core_ext/string/filters"
+require "active_support/core_ext/enumerable"
 
 loader = Zeitwerk::Loader.for_gem
 loader.enable_reloading if defined?(Rails.env) && Rails.env.development?
@@ -11,6 +13,27 @@ module FlowChat
   def self.root
     Pathname.new __dir__
   end
+
+  def self.setup_instrumentation!
+    require_relative "flow_chat/instrumentation/setup"
+    FlowChat::Instrumentation::Setup.setup_instrumentation!
+  end
+
+  # Access to instrumentation
+  def self.instrument(event_name, payload = {}, &block)
+    FlowChat::Instrumentation.instrument(event_name, payload, &block)
+  end
+
+  def self.metrics
+    FlowChat::Instrumentation::Setup.metrics_collector
+  end
 end
 
 loader.eager_load
+
+# Auto-setup instrumentation in Rails environments
+if defined?(Rails)
+  Rails.application.config.after_initialize do
+    FlowChat.setup_instrumentation!
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flow_chat
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-05 00:00:00.000000000 Z
+date: 2025-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -80,7 +80,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.4.2
-description: Framework for building Menu based conversations (e.g. USSD) in Rails.
+description: "FlowChat is a Rails framework for building sophisticated conversational
+  interfaces across USSD and WhatsApp platforms. \nCreate interactive flows with menus,
+  prompts, validation, media support, and session management. Features include \nmulti-tenancy,
+  background job processing, built-in simulator for testing, and comprehensive middleware
+  support.\n"
 email:
 - sfroelich01@gmail.com
 executables: []
@@ -88,21 +92,25 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".DS_Store"
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - ".ruby-version"
-- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - SECURITY.md
-- app/controllers/demo_controller.rb
-- app/flow_chat/demo_restaurant_flow.rb
 - bin/console
 - bin/setup
-- config/routes_demo.rb
-- examples/initializer.rb
-- examples/media_prompts_examples.rb
+- docs/configuration.md
+- docs/flows.md
+- docs/images/simulator.png
+- docs/instrumentation.md
+- docs/media.md
+- docs/sessions.md
+- docs/testing.md
+- docs/ussd-setup.md
+- docs/whatsapp-setup.md
 - examples/multi_tenant_whatsapp_controller.rb
 - examples/simulator_controller.rb
 - examples/ussd_controller.rb
@@ -110,12 +118,15 @@ files:
 - examples/whatsapp_media_examples.rb
 - examples/whatsapp_message_job.rb
 - flow_chat.gemspec
-- images/ussd_simulator.png
 - lib/flow_chat.rb
 - lib/flow_chat/base_processor.rb
 - lib/flow_chat/config.rb
 - lib/flow_chat/context.rb
 - lib/flow_chat/flow.rb
+- lib/flow_chat/instrumentation.rb
+- lib/flow_chat/instrumentation/log_subscriber.rb
+- lib/flow_chat/instrumentation/metrics_collector.rb
+- lib/flow_chat/instrumentation/setup.rb
 - lib/flow_chat/interrupt.rb
 - lib/flow_chat/prompt.rb
 - lib/flow_chat/session/cache_session_store.rb
@@ -126,9 +137,9 @@ files:
 - lib/flow_chat/ussd/app.rb
 - lib/flow_chat/ussd/gateway/nalo.rb
 - lib/flow_chat/ussd/gateway/nsano.rb
+- lib/flow_chat/ussd/middleware/choice_mapper.rb
 - lib/flow_chat/ussd/middleware/executor.rb
 - lib/flow_chat/ussd/middleware/pagination.rb
-- lib/flow_chat/ussd/middleware/resumable_session.rb
 - lib/flow_chat/ussd/processor.rb
 - lib/flow_chat/ussd/renderer.rb
 - lib/flow_chat/version.rb
@@ -167,5 +178,5 @@ requirements: []
 rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
-summary: Framework for building Menu based conversations (e.g. USSD) in Rails.
+summary: Build conversational interfaces for USSD and WhatsApp with Rails
 test_files: []

data/.travis.yml

@@ -1,6 +0,0 @@
----
-language: ruby
-cache: bundler
-rvm:
-  - 2.7.1
-before_install: gem install bundler -v 2.1.4

data/app/controllers/demo_controller.rb

@@ -1,101 +0,0 @@
-# Demo Controller - Showcases FlowChat comprehensive features
-# 
-# This controller demonstrates how to use the DemoRestaurantFlow
-# across both USSD and WhatsApp platforms, showing off all FlowChat features.
-#
-# Features demonstrated:
-# - Cross-platform compatibility
-# - Media support with graceful degradation  
-# - Complex workflows with session management
-# - Input validation and transformation
-# - Rich interactive elements
-
-class DemoController < ApplicationController
-  skip_forgery_protection
-
-  # USSD Demo Endpoint
-  # Usage: POST /demo/ussd
-  def ussd_demo
-    processor = FlowChat::Ussd::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Ussd::Gateway::Nalo
-      config.use_session_store FlowChat::Session::RailsSessionStore
-      
-      # Optional: Enable resumable sessions for better UX
-      config.use_resumable_sessions
-      
-      # Optional: Custom pagination settings for large menus
-      FlowChat::Config.ussd.pagination_page_size = 120  # Slightly larger for demo
-    end
-
-    processor.run DemoRestaurantFlow, :main_page
-  end
-
-  # WhatsApp Demo Endpoint  
-  # Usage: GET/POST /demo/whatsapp
-  def whatsapp_demo
-    processor = FlowChat::Whatsapp::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
-
-    processor.run DemoRestaurantFlow, :main_page
-  end
-
-  # Alternative WhatsApp Demo with Custom Configuration
-  # Usage: GET/POST /demo/whatsapp_custom
-  def whatsapp_custom_demo
-    # Custom configuration for multi-tenant demo
-    custom_config = FlowChat::Whatsapp::Configuration.new
-    custom_config.access_token = ENV['DEMO_WHATSAPP_ACCESS_TOKEN']
-    custom_config.phone_number_id = ENV['DEMO_WHATSAPP_PHONE_NUMBER_ID']
-    custom_config.verify_token = ENV['DEMO_WHATSAPP_VERIFY_TOKEN']
-    custom_config.app_secret = ENV['DEMO_WHATSAPP_APP_SECRET']
-    custom_config.skip_signature_validation = Rails.env.development?
-
-    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: true) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, custom_config
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
-
-    processor.run DemoRestaurantFlow, :main_page
-  end
-
-  # Background Mode Demo
-  # Usage: GET/POST /demo/whatsapp_background
-  def whatsapp_background_demo
-    # Configure for background processing
-    original_mode = FlowChat::Config.whatsapp.message_handling_mode
-    FlowChat::Config.whatsapp.message_handling_mode = :background
-    FlowChat::Config.whatsapp.background_job_class = 'DemoWhatsappJob'
-
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
-
-    processor.run DemoRestaurantFlow, :main_page
-
-  ensure
-    # Restore original mode
-    FlowChat::Config.whatsapp.message_handling_mode = original_mode
-  end
-
-  # Simulator Mode Demo (for testing)
-  # Usage: GET/POST /demo/whatsapp_simulator
-  def whatsapp_simulator_demo
-    # Force simulator mode for testing
-    original_mode = FlowChat::Config.whatsapp.message_handling_mode
-    FlowChat::Config.whatsapp.message_handling_mode = :simulator
-
-    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: true) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
-
-    processor.run DemoRestaurantFlow, :main_page
-
-  ensure
-    # Restore original mode
-    FlowChat::Config.whatsapp.message_handling_mode = original_mode
-  end
-end