flow_chat 0.6.1 → 0.7.0

data/lib/flow_chat/ussd/middleware/pagination.rb

@@ -2,23 +2,44 @@ module FlowChat
   module Ussd
     module Middleware
       class Pagination
+        include FlowChat::Instrumentation
+
+        attr_reader :context
+
         def initialize(app)
           @app = app
+          FlowChat.logger.debug { "Ussd::Pagination: Initialized USSD pagination middleware" }
         end
 
         def call(context)
           @context = context
           @session = context.session
 
+          session_id = context["session.id"]
+          FlowChat.logger.debug { "Ussd::Pagination: Processing request for session #{session_id}" }
+
           if intercept?
+            FlowChat.logger.info { "Ussd::Pagination: Intercepting request for pagination handling - session #{session_id}" }
             type, prompt = handle_intercepted_request
             [type, prompt, []]
           else
+            # Clear pagination state for new flows
+            if pagination_state.present?
+              FlowChat.logger.debug { "Ussd::Pagination: Clearing pagination state for new flow - session #{session_id}" }
+            end
             @session.delete "ussd.pagination"
+
             type, prompt, choices, media = @app.call(context)
 
             prompt = FlowChat::Ussd::Renderer.new(prompt, choices: choices, media: media).render
-            type, prompt = maybe_paginate(type, prompt) if prompt.present?
+
+            if prompt.present?
+              original_length = prompt.length
+              type, prompt = maybe_paginate(type, prompt)
+              if prompt.length != original_length
+                FlowChat.logger.info { "Ussd::Pagination: Content paginated - original: #{original_length} chars, paginated: #{prompt.length} chars" }
+              end
+            end
 
             [type, prompt, []]
           end
@@ -27,53 +48,91 @@ module FlowChat
         private
 
         def intercept?
-          pagination_state.present? &&
+          should_intercept = pagination_state.present? &&
             (pagination_state["type"].to_sym == :terminal ||
              ([FlowChat::Config.ussd.pagination_next_option, FlowChat::Config.ussd.pagination_back_option].include? @context.input))
+
+          if should_intercept
+            FlowChat.logger.debug { "Ussd::Pagination: Intercepting - input: #{@context.input}, pagination type: #{pagination_state["type"]}" }
+          end
+
+          should_intercept
         end
 
         def handle_intercepted_request
-          FlowChat::Config.logger&.info "FlowChat::Middleware::Pagination :: Intercepted to handle pagination"
+          FlowChat.logger.info { "Ussd::Pagination: Handling paginated request" }
           start, finish, has_more = calculate_offsets
           type = (pagination_state["type"].to_sym == :terminal && !has_more) ? :terminal : :prompt
           prompt = pagination_state["prompt"][start..finish] + build_pagination_options(type, has_more)
           set_pagination_state(current_page, start, finish)
 
+          # Instrument pagination navigation
+          instrument(Events::PAGINATION_TRIGGERED, {
+            session_id: @context["session.id"],
+            current_page: current_page,
+            total_pages: calculate_total_pages,
+            content_length: pagination_state["prompt"].length,
+            page_limit: FlowChat::Config.ussd.pagination_page_size,
+            navigation_action: (@context.input == FlowChat::Config.ussd.pagination_next_option) ? "next" : "back"
+          })
+
+          FlowChat.logger.debug { "Ussd::Pagination: Serving page content - start: #{start}, finish: #{finish}, has_more: #{has_more}, type: #{type}" }
           [type, prompt]
         end
 
         def maybe_paginate(type, prompt)
           if prompt.length > FlowChat::Config.ussd.pagination_page_size
             original_prompt = prompt
-            FlowChat::Config.logger&.info "FlowChat::Middleware::Pagination :: Response length (#{prompt.length}) exceeds page size (#{FlowChat::Config.ussd.pagination_page_size}). Paginating."
+            FlowChat.logger.info { "Ussd::Pagination: Content exceeds page size (#{prompt.length} > #{FlowChat::Config.ussd.pagination_page_size}), initiating pagination" }
+
             slice_end = single_option_slice_size
             # Ensure we do not cut words and options off in the middle.
             current_pagebreak = original_prompt[slice_end + 1].blank? ? slice_end : original_prompt[0..slice_end].rindex("\n") || original_prompt[0..slice_end].rindex(" ") || slice_end
+
+            FlowChat.logger.debug { "Ussd::Pagination: First page break at position #{current_pagebreak}" }
+
             set_pagination_state(1, 0, current_pagebreak, original_prompt, type)
             prompt = original_prompt[0..current_pagebreak] + "\n\n" + next_option
             type = :prompt
+
+            # Instrument initial pagination setup
+            total_pages = calculate_total_pages(original_prompt)
+            instrument(Events::PAGINATION_TRIGGERED, {
+              session_id: @context["session.id"],
+              current_page: 1,
+              total_pages: total_pages,
+              content_length: original_prompt.length,
+              page_limit: FlowChat::Config.ussd.pagination_page_size,
+              navigation_action: "initial"
+            })
+
+            FlowChat.logger.debug { "Ussd::Pagination: First page prepared with #{prompt.length} characters" }
           end
           [type, prompt]
         end
 
         def calculate_offsets
           page = current_page
+
+          FlowChat.logger.debug { "Ussd::Pagination: Calculating offsets for page #{page}" }
+
           offset = pagination_state["offsets"][page.to_s]
           if offset.present?
-            FlowChat::Config.logger&.debug "FlowChat::Middleware::Pagination :: Reusing cached offset for page: #{page}"
+            FlowChat.logger.debug { "Ussd::Pagination: Using cached offset for page #{page}" }
             start = offset["start"]
             finish = offset["finish"]
             has_more = pagination_state["prompt"].length > finish
           else
-            FlowChat::Config.logger&.debug "FlowChat::Middleware::Pagination :: Calculating offset for page: #{page}"
+            FlowChat.logger.debug { "Ussd::Pagination: Computing new offset for page #{page}" }
             # We are guaranteed a previous offset because it was set in maybe_paginate
             previous_page = page - 1
             previous_offset = pagination_state["offsets"][previous_page.to_s]
             start = previous_offset["finish"] + 1
             has_more, len = (pagination_state["prompt"].length > start + single_option_slice_size) ? [true, dual_options_slice_size] : [false, single_option_slice_size]
             finish = start + len
+
             if start > pagination_state["prompt"].length
-              FlowChat::Config.logger&.debug "FlowChat::Middleware::Pagination :: No content exists for page: #{page}. Reverting to page: #{page - 1}"
+              FlowChat.logger.warn { "Ussd::Pagination: No content for page #{page}, reverting to page #{page - 1}" }
               page -= 1
               has_more = false
               start = previous_offset["start"]
@@ -90,19 +149,26 @@ module FlowChat
                   # We're in the middle of a word, find the last word boundary
                   boundary_pos = slice_text.rindex("\n") || slice_text.rindex(" ")
                   if boundary_pos
+                    old_finish = finish
                     finish = start + boundary_pos
+                    FlowChat.logger.debug { "Ussd::Pagination: Adjusted finish for word boundary - #{old_finish} -> #{finish}" }
                   end
                   # If no boundary found, we'll have to break mid-word (fallback)
                 end
               end
             end
           end
+
+          FlowChat.logger.debug { "Ussd::Pagination: Page #{page} offsets - start: #{start}, finish: #{finish}, has_more: #{has_more}" }
           [start, finish, has_more]
         end
 
         def build_pagination_options(type, has_more)
           options_str = ""
           has_less = current_page > 1
+
+          FlowChat.logger.debug { "Ussd::Pagination: Building pagination options - type: #{type}, has_more: #{has_more}, has_less: #{has_less}" }
+
           if type.to_sym == :prompt
             options_str += "\n\n"
             next_opt = has_more ? next_option : ""
@@ -126,6 +192,7 @@ module FlowChat
             # We accomodate the 2 newlines and the longest of the options
             # We subtract an additional 1 to normalize it for slicing
             @single_option_slice_size = FlowChat::Config.ussd.pagination_page_size - 2 - [next_option.length, back_option.length].max - 1
+            FlowChat.logger.debug { "Ussd::Pagination: Calculated single option slice size: #{@single_option_slice_size}" }
           end
           @single_option_slice_size
         end
@@ -135,6 +202,7 @@ module FlowChat
             # To display both back and next options
             # We accomodate the 3 newlines and both of the options
             @dual_options_slice_size = FlowChat::Config.ussd.pagination_page_size - 3 - [next_option.length, back_option.length].sum - 1
+            FlowChat.logger.debug { "Ussd::Pagination: Calculated dual options slice size: #{@dual_options_slice_size}" }
           end
           @dual_options_slice_size
         end
@@ -143,8 +211,10 @@ module FlowChat
           page = pagination_state["page"]
           if @context.input == FlowChat::Config.ussd.pagination_back_option
             page -= 1
+            FlowChat.logger.debug { "Ussd::Pagination: Moving to previous page: #{page}" }
           elsif @context.input == FlowChat::Config.ussd.pagination_next_option
             page += 1
+            FlowChat.logger.debug { "Ussd::Pagination: Moving to next page: #{page}" }
           end
           [page, 1].max
         end
@@ -165,8 +235,18 @@ module FlowChat
             "prompt" => prompt,
             "type" => type.to_s
           }
+
+          FlowChat.logger.debug { "Ussd::Pagination: Saving pagination state - page: #{page}, total_content: #{prompt&.length || 0} chars" }
           @session.set "ussd.pagination", new_state
         end
+
+        def calculate_total_pages(content = nil)
+          content ||= pagination_state["prompt"]
+          return 1 unless content&.length&.> FlowChat::Config.ussd.pagination_page_size
+
+          # Rough estimation - actual pages may vary due to word boundaries
+          (content.length.to_f / single_option_slice_size).ceil
+        end
       end
     end
   end

data/lib/flow_chat/ussd/processor.rb

@@ -2,6 +2,7 @@ module FlowChat
   module Ussd
     class Processor < FlowChat::BaseProcessor
       def use_resumable_sessions
+        FlowChat.logger.debug { "Ussd::Processor: Enabling resumable sessions middleware" }
         middleware.insert_before 0, FlowChat::Ussd::Middleware::ResumableSession
         self
       end
@@ -13,14 +14,27 @@ module FlowChat
       end
 
       def build_middleware_stack
+        FlowChat.logger.debug { "Ussd::Processor: Building USSD middleware stack" }
         create_middleware_stack("ussd")
       end
 
       def configure_middleware_stack(builder)
+        FlowChat.logger.debug { "Ussd::Processor: Configuring USSD middleware stack" }
+
         builder.use FlowChat::Session::Middleware
+        FlowChat.logger.debug { "Ussd::Processor: Added Session::Middleware" }
+
         builder.use FlowChat::Ussd::Middleware::Pagination
+        FlowChat.logger.debug { "Ussd::Processor: Added Ussd::Middleware::Pagination" }
+
         builder.use middleware
+        FlowChat.logger.debug { "Ussd::Processor: Added custom middleware" }
+
+        builder.use FlowChat::Ussd::Middleware::ChoiceMapper
+        FlowChat.logger.debug { "Ussd::Processor: Added Ussd::Middleware::ChoiceMapper" }
+
         builder.use FlowChat::Ussd::Middleware::Executor
+        FlowChat.logger.debug { "Ussd::Processor: Added Ussd::Middleware::Executor" }
       end
     end
   end

data/lib/flow_chat/ussd/renderer.rb

@@ -14,7 +14,7 @@ module FlowChat
       private
 
       def build_prompt
-        parts = [prompt, build_media, build_choices].compact
+        parts = [build_media, prompt, build_choices].compact
         parts.join "\n\n"
       end
 

data/lib/flow_chat/version.rb

@@ -1,3 +1,3 @@
 module FlowChat
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

data/lib/flow_chat/whatsapp/client.rb

@@ -7,8 +7,12 @@ require "securerandom"
 module FlowChat
   module Whatsapp
     class Client
+      include FlowChat::Instrumentation
+
       def initialize(config)
         @config = config
+        FlowChat.logger.info { "WhatsApp::Client: Initialized WhatsApp client for phone_number_id: #{@config.phone_number_id}" }
+        FlowChat.logger.debug { "WhatsApp::Client: API base URL: #{FlowChat::Config.whatsapp.api_base_url}" }
       end
 
       # Send a message to a WhatsApp number
@@ -16,8 +20,28 @@ module FlowChat
       # @param response [Array] FlowChat response array [type, content, options]
       # @return [Hash] API response or nil on error
       def send_message(to, response)
-        message_data = build_message_payload(response, to)
-        send_message_payload(message_data)
+        type, content, _ = response
+        FlowChat.logger.info { "WhatsApp::Client: Sending #{type} message to #{to}" }
+        FlowChat.logger.debug { "WhatsApp::Client: Message content: '#{content.to_s.truncate(100)}'" }
+
+        result = instrument(Events::MESSAGE_SENT, {
+          to: to,
+          message_type: type.to_s,
+          content_length: content.to_s.length,
+          platform: :whatsapp
+        }) do
+          message_data = build_message_payload(response, to)
+          send_message_payload(message_data)
+        end
+
+        if result
+          message_id = result.dig("messages", 0, "id")
+          FlowChat.logger.debug { "WhatsApp::Client: Message sent successfully to #{to}, message_id: #{message_id}" }
+        else
+          FlowChat.logger.error { "WhatsApp::Client: Failed to send message to #{to}" }
+        end
+
+        result
       end
 
       # Send a text message
@@ -25,6 +49,7 @@ module FlowChat
       # @param text [String] Message text
       # @return [Hash] API response or nil on error
       def send_text(to, text)
+        FlowChat.logger.debug { "WhatsApp::Client: Sending text message to #{to}" }
         send_message(to, [:text, text, {}])
       end
 
@@ -34,6 +59,7 @@ module FlowChat
       # @param buttons [Array] Array of button hashes with :id and :title
       # @return [Hash] API response or nil on error
       def send_buttons(to, text, buttons)
+        FlowChat.logger.debug { "WhatsApp::Client: Sending interactive buttons to #{to} with #{buttons.size} buttons" }
         send_message(to, [:interactive_buttons, text, {buttons: buttons}])
       end
 
@@ -44,6 +70,8 @@ module FlowChat
       # @param button_text [String] Button text (default: "Choose")
       # @return [Hash] API response or nil on error
       def send_list(to, text, sections, button_text = "Choose")
+        total_items = sections.sum { |section| section[:rows]&.size || 0 }
+        FlowChat.logger.debug { "WhatsApp::Client: Sending interactive list to #{to} with #{sections.size} sections, #{total_items} total items" }
         send_message(to, [:interactive_list, text, {sections: sections, button_text: button_text}])
       end
 
@@ -54,6 +82,7 @@ module FlowChat
       # @param language [String] Language code (default: "en_US")
       # @return [Hash] API response or nil on error
       def send_template(to, template_name, components = [], language = "en_US")
+        FlowChat.logger.debug { "WhatsApp::Client: Sending template '#{template_name}' to #{to} in #{language}" }
         send_message(to, [:template, "", {
           template_name: template_name,
           components: components,
@@ -68,6 +97,7 @@ module FlowChat
       # @param mime_type [String] Optional MIME type for URLs (e.g., 'image/jpeg')
       # @return [Hash] API response
       def send_image(to, image_url_or_id, caption = nil, mime_type = nil)
+        FlowChat.logger.debug { "WhatsApp::Client: Sending image to #{to} - #{url?(image_url_or_id) ? "URL" : "Media ID"}" }
         send_media_message(to, :image, image_url_or_id, caption: caption, mime_type: mime_type)
       end
 
@@ -80,6 +110,7 @@ module FlowChat
       # @return [Hash] API response
       def send_document(to, document_url_or_id, caption = nil, filename = nil, mime_type = nil)
         filename ||= extract_filename_from_url(document_url_or_id) if url?(document_url_or_id)
+        FlowChat.logger.debug { "WhatsApp::Client: Sending document to #{to} - filename: #{filename}" }
         send_media_message(to, :document, document_url_or_id, caption: caption, filename: filename, mime_type: mime_type)
       end
 
@@ -90,6 +121,7 @@ module FlowChat
       # @param mime_type [String] Optional MIME type for URLs (e.g., 'video/mp4')
       # @return [Hash] API response
       def send_video(to, video_url_or_id, caption = nil, mime_type = nil)
+        FlowChat.logger.debug { "WhatsApp::Client: Sending video to #{to}" }
         send_media_message(to, :video, video_url_or_id, caption: caption, mime_type: mime_type)
       end
 
@@ -99,6 +131,7 @@ module FlowChat
       # @param mime_type [String] Optional MIME type for URLs (e.g., 'audio/mpeg')
       # @return [Hash] API response
       def send_audio(to, audio_url_or_id, mime_type = nil)
+        FlowChat.logger.debug { "WhatsApp::Client: Sending audio to #{to}" }
         send_media_message(to, :audio, audio_url_or_id, mime_type: mime_type)
       end
 
@@ -108,6 +141,7 @@ module FlowChat
       # @param mime_type [String] Optional MIME type for URLs (e.g., 'image/webp')
       # @return [Hash] API response
       def send_sticker(to, sticker_url_or_id, mime_type = nil)
+        FlowChat.logger.debug { "WhatsApp::Client: Sending sticker to #{to}" }
         send_media_message(to, :sticker, sticker_url_or_id, mime_type: mime_type)
       end
 
@@ -118,17 +152,23 @@ module FlowChat
       # @return [String] Media ID
       # @raise [StandardError] If upload fails
       def upload_media(file_path_or_io, mime_type, filename = nil)
+        FlowChat.logger.info { "WhatsApp::Client: Uploading media file - type: #{mime_type}, filename: #{filename}" }
+
         raise ArgumentError, "mime_type is required" if mime_type.nil? || mime_type.empty?
 
+        file_size = nil
         if file_path_or_io.is_a?(String)
           # File path
           raise ArgumentError, "File not found: #{file_path_or_io}" unless File.exist?(file_path_or_io)
           filename ||= File.basename(file_path_or_io)
+          file_size = File.size(file_path_or_io)
+          FlowChat.logger.debug { "WhatsApp::Client: Uploading file from path: #{file_path_or_io} (#{file_size} bytes)" }
           file = File.open(file_path_or_io, "rb")
         else
           # IO object
           file = file_path_or_io
           filename ||= "upload"
+          FlowChat.logger.debug { "WhatsApp::Client: Uploading file from IO object" }
         end
 
         # Upload directly via HTTP
@@ -136,6 +176,8 @@ module FlowChat
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = true
 
+        FlowChat.logger.debug { "WhatsApp::Client: Uploading to #{uri}" }
+
         # Prepare multipart form data
         boundary = "----WebKitFormBoundary#{SecureRandom.hex(16)}"
 
@@ -165,15 +207,45 @@ module FlowChat
         request["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
         request.body = body
 
-        response = http.request(request)
-
-        if response.is_a?(Net::HTTPSuccess)
-          data = JSON.parse(response.body)
-          data["id"] || raise(StandardError, "Failed to upload media: #{data}")
-        else
-          Rails.logger.error "WhatsApp Media Upload error: #{response.body}"
-          raise StandardError, "Media upload failed: #{response.body}"
+        result = instrument(Events::MEDIA_UPLOAD, {
+          filename: filename,
+          mime_type: mime_type,
+          size: file_size,
+          platform: :whatsapp
+        }) do
+          response = http.request(request)
+
+          if response.is_a?(Net::HTTPSuccess)
+            data = JSON.parse(response.body)
+            media_id = data["id"]
+            if media_id
+              FlowChat.logger.info { "WhatsApp::Client: Media upload successful - media_id: #{media_id}" }
+              {success: true, media_id: media_id}
+            else
+              FlowChat.logger.error { "WhatsApp::Client: Media upload failed - no media_id in response: #{data}" }
+              raise StandardError, "Failed to upload media: #{data}"
+            end
+          else
+            FlowChat.logger.error { "WhatsApp::Client: Media upload error - #{response.code}: #{response.body}" }
+            raise StandardError, "Media upload failed: #{response.body}"
+          end
         end
+
+        result[:media_id]
+      rescue => error
+        FlowChat.logger.error { "WhatsApp::Client: Media upload exception: #{error.class.name}: #{error.message}" }
+
+        # Instrument the error
+        instrument(Events::MEDIA_UPLOAD, {
+          filename: filename,
+          mime_type: mime_type,
+          size: file_size,
+          success: false,
+          error: error.message,
+          platform: :whatsapp
+        })
+
+        raise
       ensure
         file&.close if file_path_or_io.is_a?(String)
       end
@@ -394,6 +466,11 @@ module FlowChat
       # @param message_data [Hash] Message payload
       # @return [Hash] API response or nil on error
       def send_message_payload(message_data)
+        to = message_data[:to]
+        message_type = message_data[:type]
+
+        FlowChat.logger.debug { "WhatsApp::Client: Sending API request to #{to} - type: #{message_type}" }
+
         uri = URI("#{FlowChat::Config.whatsapp.api_base_url}/#{@config.phone_number_id}/messages")
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = true
@@ -403,14 +480,24 @@ module FlowChat
         request["Content-Type"] = "application/json"
         request.body = message_data.to_json
 
+        FlowChat.logger.debug { "WhatsApp::Client: Making HTTP request to WhatsApp API" }
         response = http.request(request)
 
         if response.is_a?(Net::HTTPSuccess)
-          JSON.parse(response.body)
+          result = JSON.parse(response.body)
+          FlowChat.logger.debug { "WhatsApp::Client: API request successful - response: #{result}" }
+          result
         else
-          Rails.logger.error "WhatsApp API error: #{response.body}"
+          FlowChat.logger.error { "WhatsApp::Client: API request failed - #{response.code}: #{response.body}" }
           nil
         end
+      rescue Net::OpenTimeout, Net::ReadTimeout => network_error
+        # Let network timeouts bubble up for proper error handling
+        FlowChat.logger.error { "WhatsApp::Client: Network timeout: #{network_error.class.name}: #{network_error.message}" }
+        raise network_error
+      rescue => error
+        FlowChat.logger.error { "WhatsApp::Client: API request exception: #{error.class.name}: #{error.message}" }
+        nil
       end
 
       def send_media_message(to, media_type, url_or_id, caption: nil, filename: nil, mime_type: nil)

data/lib/flow_chat/whatsapp/configuration.rb

@@ -18,14 +18,19 @@ module FlowChat
         @business_account_id = nil
         @skip_signature_validation = false
 
+        FlowChat.logger.debug { "WhatsApp::Configuration: Initialized configuration with name: #{name || "anonymous"}" }
+
         register_as(name) if name.present?
       end
 
       # Load configuration from Rails credentials or environment variables
       def self.from_credentials
+        FlowChat.logger.info { "WhatsApp::Configuration: Loading configuration from credentials/environment" }
+
         config = new(nil)
 
         if defined?(Rails) && Rails.application.credentials.whatsapp
+          FlowChat.logger.debug { "WhatsApp::Configuration: Loading from Rails credentials" }
           credentials = Rails.application.credentials.whatsapp
           config.access_token = credentials[:access_token]
           config.phone_number_id = credentials[:phone_number_id]
@@ -35,6 +40,7 @@ module FlowChat
           config.business_account_id = credentials[:business_account_id]
           config.skip_signature_validation = credentials[:skip_signature_validation] || false
         else
+          FlowChat.logger.debug { "WhatsApp::Configuration: Loading from environment variables" }
           # Fallback to environment variables
           config.access_token = ENV["WHATSAPP_ACCESS_TOKEN"]
           config.phone_number_id = ENV["WHATSAPP_PHONE_NUMBER_ID"]
@@ -45,43 +51,68 @@ module FlowChat
           config.skip_signature_validation = ENV["WHATSAPP_SKIP_SIGNATURE_VALIDATION"] == "true"
         end
 
+        if config.valid?
+          FlowChat.logger.info { "WhatsApp::Configuration: Configuration loaded successfully - phone_number_id: #{config.phone_number_id}" }
+        else
+          FlowChat.logger.warn { "WhatsApp::Configuration: Incomplete configuration loaded - missing required fields" }
+        end
+
         config
       end
 
       # Register a named configuration
       def self.register(name, config)
+        FlowChat.logger.debug { "WhatsApp::Configuration: Registering configuration '#{name}'" }
         @@configurations[name.to_sym] = config
       end
 
       # Get a named configuration
       def self.get(name)
-        @@configurations[name.to_sym] || raise(ArgumentError, "WhatsApp configuration '#{name}' not found")
+        config = @@configurations[name.to_sym]
+        if config
+          FlowChat.logger.debug { "WhatsApp::Configuration: Retrieved configuration '#{name}'" }
+          config
+        else
+          FlowChat.logger.error { "WhatsApp::Configuration: Configuration '#{name}' not found" }
+          raise ArgumentError, "WhatsApp configuration '#{name}' not found"
+        end
       end
 
       # Check if a named configuration exists
       def self.exists?(name)
-        @@configurations.key?(name.to_sym)
+        exists = @@configurations.key?(name.to_sym)
+        FlowChat.logger.debug { "WhatsApp::Configuration: Configuration '#{name}' exists: #{exists}" }
+        exists
       end
 
       # Get all configuration names
       def self.configuration_names
-        @@configurations.keys
+        names = @@configurations.keys
+        FlowChat.logger.debug { "WhatsApp::Configuration: Available configurations: #{names}" }
+        names
       end
 
       # Clear all registered configurations (useful for testing)
       def self.clear_all!
+        FlowChat.logger.debug { "WhatsApp::Configuration: Clearing all registered configurations" }
         @@configurations.clear
       end
 
       # Register this configuration with a name
       def register_as(name)
+        FlowChat.logger.debug { "WhatsApp::Configuration: Registering configuration as '#{name}'" }
         @name = name.to_sym
         self.class.register(@name, self)
         self
       end
 
       def valid?
-        access_token && !access_token.to_s.empty? && phone_number_id && !phone_number_id.to_s.empty? && verify_token && !verify_token.to_s.empty?
+        is_valid = access_token && !access_token.to_s.empty? &&
+          phone_number_id && !phone_number_id.to_s.empty? &&
+          verify_token && !verify_token.to_s.empty?
+
+        FlowChat.logger.debug { "WhatsApp::Configuration: Configuration valid: #{is_valid}" }
+        is_valid
       end
 
       # API endpoints