flow_chat 0.6.0 → 0.7.0

data/lib/flow_chat/whatsapp/gateway/cloud_api.rb

@@ -10,26 +10,39 @@ module FlowChat
 
     module Gateway
       class CloudApi
+        include FlowChat::Instrumentation
+
+        attr_reader :context
+
         def initialize(app, config = nil)
           @app = app
           @config = config || FlowChat::Whatsapp::Configuration.from_credentials
           @client = FlowChat::Whatsapp::Client.new(@config)
+
+          FlowChat.logger.info { "CloudApi: Initialized WhatsApp Cloud API gateway with phone_number_id: #{@config.phone_number_id}" }
+          FlowChat.logger.debug { "CloudApi: Gateway configuration - API base URL: #{FlowChat::Config.whatsapp.api_base_url}" }
         end
 
         def call(context)
+          @context = context
           controller = context.controller
           request = controller.request
 
+          FlowChat.logger.debug { "CloudApi: Processing #{request.request_method} request to #{request.path}" }
+
           # Handle webhook verification
           if request.get? && request.params["hub.mode"] == "subscribe"
+            FlowChat.logger.info { "CloudApi: Handling webhook verification request" }
             return handle_verification(context)
           end
 
           # Handle webhook messages
           if request.post?
+            FlowChat.logger.info { "CloudApi: Handling webhook message" }
             return handle_webhook(context)
           end
 
+          FlowChat.logger.warn { "CloudApi: Invalid request method or parameters - returning bad request" }
           controller.head :bad_request
         end
 
@@ -41,11 +54,14 @@ module FlowChat
         def determine_message_handler(context)
           # Check if simulator mode was already detected and set in context
           if context["simulator_mode"]
+            FlowChat.logger.debug { "CloudApi: Using simulator message handler" }
             return :simulator
           end
 
           # Use global WhatsApp configuration
-          FlowChat::Config.whatsapp.message_handling_mode
+          mode = FlowChat::Config.whatsapp.message_handling_mode
+          FlowChat.logger.debug { "CloudApi: Using #{mode} message handling mode" }
+          mode
         end
 
         def handle_verification(context)
@@ -53,93 +69,127 @@ module FlowChat
           params = controller.request.params
 
           verify_token = @config.verify_token
+          provided_token = params["hub.verify_token"]
+          challenge = params["hub.challenge"]
 
-          if params["hub.verify_token"] == verify_token
-            controller.render plain: params["hub.challenge"]
+          FlowChat.logger.debug { "CloudApi: Webhook verification - provided token matches: #{provided_token == verify_token}" }
+
+          if provided_token == verify_token
+            # Use instrumentation for webhook verification success
+            instrument(Events::WEBHOOK_VERIFIED, {
+              challenge: challenge,
+              platform: :whatsapp
+            })
+
+            controller.render plain: challenge
           else
+            # Use instrumentation for webhook verification failure
+            instrument(Events::WEBHOOK_FAILED, {
+              reason: "Invalid verify token",
+              platform: :whatsapp
+            })
+
             controller.head :forbidden
           end
         end
 
         def handle_webhook(context)
           controller = context.controller
-          
+
           # Parse body
           begin
             parse_request_body(controller.request)
+            FlowChat.logger.debug { "CloudApi: Successfully parsed webhook request body" }
           rescue JSON::ParserError => e
-            Rails.logger.warn "Failed to parse webhook body: #{e.message}"
+            FlowChat.logger.error { "CloudApi: Failed to parse webhook body: #{e.message}" }
             return controller.head :bad_request
           end
-          
+
           # Check for simulator mode parameter in request (before validation)
           # But only enable if valid simulator token is provided
           is_simulator_mode = simulate?(context)
           if is_simulator_mode
+            FlowChat.logger.info { "CloudApi: Simulator mode enabled for this request" }
             context["simulator_mode"] = true
           end
 
           # Validate webhook signature for security (skip for simulator mode)
           unless is_simulator_mode || valid_webhook_signature?(controller.request)
-            Rails.logger.warn "Invalid webhook signature received"
+            FlowChat.logger.warn { "CloudApi: Invalid webhook signature received - rejecting request" }
             return controller.head :unauthorized
           end
 
+          FlowChat.logger.debug { "CloudApi: Webhook signature validation passed" }
+
           # Extract message data from WhatsApp webhook
           entry = @body.dig("entry", 0)
-          return controller.head :ok unless entry
+          unless entry
+            FlowChat.logger.debug { "CloudApi: No entry found in webhook body - returning OK" }
+            return controller.head :ok
+          end
 
           changes = entry.dig("changes", 0)
-          return controller.head :ok unless changes
+          unless changes
+            FlowChat.logger.debug { "CloudApi: No changes found in webhook entry - returning OK" }
+            return controller.head :ok
+          end
 
           value = changes["value"]
-          return controller.head :ok unless value
+          unless value
+            FlowChat.logger.debug { "CloudApi: No value found in webhook changes - returning OK" }
+            return controller.head :ok
+          end
 
           # Handle incoming messages
           if value["messages"]&.any?
             message = value["messages"].first
             contact = value["contacts"]&.first
 
-            context["request.id"] = message["from"]
+            phone_number = message["from"]
+            message_id = message["id"]
+            contact_name = contact&.dig("profile", "name")
+
+            # Use instrumentation for message received
+            instrument(Events::MESSAGE_RECEIVED, {
+              from: phone_number,
+              message: context.input,
+              message_type: message["type"],
+              message_id: message_id,
+              platform: :whatsapp
+            })
+
+            context["request.id"] = phone_number
             context["request.gateway"] = :whatsapp_cloud_api
-            context["request.message_id"] = message["id"]
-            context["request.msisdn"] = Phonelib.parse(message["from"]).e164
-            context["request.contact_name"] = contact&.dig("profile", "name")
+            context["request.message_id"] = message_id
+            context["request.msisdn"] = Phonelib.parse(phone_number).e164
+            context["request.contact_name"] = contact_name
             context["request.timestamp"] = message["timestamp"]
 
             # Extract message content based on type
             extract_message_content(message, context)
 
+            FlowChat.logger.debug { "CloudApi: Message content extracted - Type: #{message["type"]}, Input: '#{context.input}'" }
+
             # Determine message handling mode
             handler_mode = determine_message_handler(context)
 
             # Process the message based on handling mode
-            begin
-              case handler_mode
-              when :inline
-                handle_message_inline(context, controller)
-              when :background
-                handle_message_background(context, controller)
-              when :simulator
-                # Return early from simulator mode to preserve the JSON response
-                return handle_message_simulator(context, controller)
-              end
-            rescue => e
-              # Log the error and set appropriate HTTP status
-              Rails.logger.error "Error processing WhatsApp message: #{e.message}"
-              Rails.logger.error e.backtrace&.join("\n") if e.backtrace
-              
-              # Return error status to WhatsApp so they know processing failed
-              controller.head :internal_server_error
-              
-              # Re-raise the error to bubble it up for proper error tracking/monitoring
-              raise e
+            case handler_mode
+            when :inline
+              handle_message_inline(context, controller)
+            when :background
+              handle_message_background(context, controller)
+            when :simulator
+              # Return early from simulator mode to preserve the JSON response
+              return handle_message_simulator(context, controller)
             end
           end
 
           # Handle message status updates
           if value["statuses"]&.any?
-            Rails.logger.info "WhatsApp status update: #{value["statuses"]}"
+            statuses = value["statuses"]
+            FlowChat.logger.info { "CloudApi: Received #{statuses.size} status update(s)" }
+            FlowChat.logger.debug { "CloudApi: Status updates: #{statuses.inspect}" }
           end
 
           controller.head :ok
@@ -149,18 +199,23 @@ module FlowChat
         def valid_webhook_signature?(request)
           # Check if signature validation is explicitly disabled
           if @config.skip_signature_validation
+            FlowChat.logger.debug { "CloudApi: Webhook signature validation is disabled" }
             return true
           end
 
           # Require app_secret for signature validation
           unless @config.app_secret && !@config.app_secret.empty?
-            raise FlowChat::Whatsapp::ConfigurationError, 
-              "WhatsApp app_secret is required for webhook signature validation. " \
-              "Either configure app_secret or set skip_signature_validation=true to explicitly disable validation."
+            error_msg = "WhatsApp app_secret is required for webhook signature validation. " \
+                       "Either configure app_secret or set skip_signature_validation=true to explicitly disable validation."
+            FlowChat.logger.error { "CloudApi: #{error_msg}" }
+            raise FlowChat::Whatsapp::ConfigurationError, error_msg
           end
 
           signature_header = request.headers["X-Hub-Signature-256"]
-          return false unless signature_header
+          unless signature_header
+            FlowChat.logger.warn { "CloudApi: No X-Hub-Signature-256 header found in request" }
+            return false
+          end
 
           # Extract signature from header (format: "sha256=<signature>")
           expected_signature = signature_header.sub("sha256=", "")
@@ -178,11 +233,19 @@ module FlowChat
           )
 
           # Compare signatures using secure comparison to prevent timing attacks
-          secure_compare(expected_signature, calculated_signature)
+          signature_valid = secure_compare(expected_signature, calculated_signature)
+
+          if signature_valid
+            FlowChat.logger.debug { "CloudApi: Webhook signature validation successful" }
+          else
+            FlowChat.logger.warn { "CloudApi: Webhook signature validation failed - signatures do not match" }
+          end
+
+          signature_valid
         rescue FlowChat::Whatsapp::ConfigurationError
           raise
         rescue => e
-          Rails.logger.error "Error validating webhook signature: #{e.message}"
+          FlowChat.logger.error { "CloudApi: Error validating webhook signature: #{e.class.name}: #{e.message}" }
           false
         end
 
@@ -197,24 +260,35 @@ module FlowChat
         end
 
         def extract_message_content(message, context)
-          case message["type"]
+          message_type = message["type"]
+          FlowChat.logger.debug { "CloudApi: Extracting content from #{message_type} message" }
+
+          case message_type
           when "text"
-            context.input = message.dig("text", "body")
+            content = message.dig("text", "body")
+            context.input = content
+            FlowChat.logger.debug { "CloudApi: Text message content: '#{content}'" }
           when "interactive"
             # Handle button/list replies
             if message.dig("interactive", "type") == "button_reply"
-              context.input = message.dig("interactive", "button_reply", "id")
+              content = message.dig("interactive", "button_reply", "id")
+              context.input = content
+              FlowChat.logger.debug { "CloudApi: Button reply ID: '#{content}'" }
             elsif message.dig("interactive", "type") == "list_reply"
-              context.input = message.dig("interactive", "list_reply", "id")
+              content = message.dig("interactive", "list_reply", "id")
+              context.input = content
+              FlowChat.logger.debug { "CloudApi: List reply ID: '#{content}'" }
             end
           when "location"
-            context["request.location"] = {
+            location = {
               latitude: message.dig("location", "latitude"),
               longitude: message.dig("location", "longitude"),
               name: message.dig("location", "name"),
               address: message.dig("location", "address")
             }
+            context["request.location"] = location
             context.input = "$location$"
+            FlowChat.logger.debug { "CloudApi: Location received - Lat: #{location[:latitude]}, Lng: #{location[:longitude]}" }
           when "image", "document", "audio", "video"
             context["request.media"] = {
               type: message["type"],
@@ -243,7 +317,7 @@ module FlowChat
           if response
             _type, prompt, choices, media = response
             rendered_message = render_response(prompt, choices, media)
-            
+
             # Queue only the response delivery asynchronously
             send_data = {
               msisdn: context["request.msisdn"],
@@ -273,7 +347,7 @@ module FlowChat
           if response
             _type, prompt, choices, media = response
             rendered_message = render_response(prompt, choices, media)
-            
+
             # For simulator mode, return the response data in the HTTP response
             # instead of actually sending via WhatsApp API
             message_payload = @client.build_message_payload(rendered_message, context["request.msisdn"])
@@ -297,7 +371,7 @@ module FlowChat
         def simulate?(context)
           # Check if simulator mode is enabled for this processor
           return false unless context["enable_simulator"]
-          
+
           # Then check if simulator mode is requested and valid
           @body.dig("simulator_mode") && valid_simulator_cookie?(context)
         end
@@ -305,27 +379,27 @@ module FlowChat
         def valid_simulator_cookie?(context)
           simulator_secret = FlowChat::Config.simulator_secret
           return false unless simulator_secret && !simulator_secret.empty?
-          
+
           # Check for simulator cookie
           request = context.controller.request
           simulator_cookie = request.cookies["flowchat_simulator"]
           return false unless simulator_cookie
-          
+
           # Verify the cookie is a valid HMAC signature
           # Cookie format: "timestamp:signature" where signature = HMAC(simulator_secret, "simulator:timestamp")
           begin
             timestamp_str, signature = simulator_cookie.split(":", 2)
             return false unless timestamp_str && signature
-            
+
             # Check timestamp is recent (within 24 hours for reasonable session duration)
             timestamp = timestamp_str.to_i
             return false if timestamp <= 0
             return false if (Time.now.to_i - timestamp).abs > 86400 # 24 hours
-            
+
             # Calculate expected signature
             message = "simulator:#{timestamp_str}"
             expected_signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), simulator_secret, message)
-            
+
             # Use secure comparison
             secure_compare(signature, expected_signature)
           rescue => e

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,20 @@ 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)
+        FlowChat.logger.debug { "Whatsapp::Processor: Configuring WhatsApp middleware stack" }
         builder.use FlowChat::Session::Middleware
+        FlowChat.logger.debug { "Whatsapp::Processor: Added Session::Middleware" }
+
         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.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-05 00:00:00.000000000 Z
+date: 2025-06-07 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,24 @@ 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/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 +117,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,6 +136,7 @@ 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
@@ -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