flow_chat 0.8.2 → 0.9.0

data/lib/flow_chat/whatsapp/client.rb

@@ -19,10 +19,13 @@ module FlowChat
       # @param to [String] Phone number in E.164 format
       # @param response [Array] FlowChat response array [type, content, options]
       # @return [Hash] API response or nil on error
-      def send_message(to, response)
-        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)}'" }
+      def send_message(to, prompt, choices: nil, media: nil)
+        FlowChat.logger.info { "WhatsApp::Client: Sending message to #{to}" }
+        FlowChat.logger.debug { "WhatsApp::Client: Message content: '#{prompt.to_s.truncate(100)}'" }
+
+        # Use renderer to convert to structured response
+        response = FlowChat::Whatsapp::Renderer.new(prompt, choices: choices, media: media).render
+        type, content, _options = response
 
         result = instrument(Events::MESSAGE_SENT, {
           to: to,
@@ -50,7 +53,7 @@ module FlowChat
       # @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, {}])
+        send_message(to, text)
       end
 
       # Send interactive buttons
@@ -60,7 +63,8 @@ module FlowChat
       # @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}])
+        choices = buttons.each_with_object({}) { |button, hash| hash[button[:id]] = button[:title] }
+        send_message(to, text, choices: choices)
       end
 
       # Send interactive list
@@ -72,7 +76,9 @@ module FlowChat
       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}])
+        choices = {}
+        sections.each { |section| section[:rows]&.each { |row| choices[row[:id]] = row[:title] } }
+        send_message(to, text, choices: choices)
       end
 
       # Send a template message
@@ -83,11 +89,13 @@ module FlowChat
       # @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, "", {
+        media = {
+          type: :template,
           template_name: template_name,
           components: components,
           language: language
-        }])
+        }
+        send_message(to, "", media: media)
       end
 
       # Send image message
@@ -98,7 +106,12 @@ module FlowChat
       # @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)
+        media = if url?(image_url_or_id)
+          {type: :image, url: image_url_or_id}
+        else
+          {type: :image, id: image_url_or_id}
+        end
+        send_message(to, caption, media: media)
       end
 
       # Send document message
@@ -145,6 +158,41 @@ module FlowChat
         send_media_message(to, :sticker, sticker_url_or_id, mime_type: mime_type)
       end
 
+      # Mark an inbound message as read, optionally showing a typing indicator.
+      #
+      # WhatsApp Cloud API ties the typing indicator to the mark-as-read call:
+      # passing `typing: true` adds a `typing_indicator` field to the same
+      # request. The indicator auto-dismisses on the next outbound message or
+      # after ~25 seconds; there is no separate "stop typing" call.
+      #
+      # @param message_id [String] the inbound message id (wamid.*) to mark as read
+      # @param typing [Boolean] when true, also show a typing indicator
+      # @return [Hash, nil] parsed API response, or nil on failure
+      def mark_as_read(message_id, typing: false)
+        payload = {
+          messaging_product: "whatsapp",
+          status: "read",
+          message_id: message_id
+        }
+        payload[:typing_indicator] = {type: "text"} if typing
+
+        send_read_receipt_payload(payload, message_id)
+      end
+
+      # Show a typing indicator in response to an inbound message.
+      #
+      # Convenience wrapper around `mark_as_read(message_id, typing: true)`.
+      # Note that WhatsApp ties the typing indicator to read-receipt delivery,
+      # so calling this also marks the message as read. There is no stop-typing
+      # call — the indicator auto-dismisses on the next outbound message or
+      # after ~25 seconds.
+      #
+      # @param message_id [String] the inbound message id (wamid.*)
+      # @return [Hash, nil] parsed API response, or nil on failure
+      def indicate_typing(message_id)
+        mark_as_read(message_id, typing: true)
+      end
+
       # Upload media file and return media ID
       # @param file_path_or_io [String, IO] File path or IO object
       # @param mime_type [String] MIME type of the file (required)
@@ -379,7 +427,7 @@ module FlowChat
           data = JSON.parse(response.body)
           data["url"]
         else
-          Rails.logger.error "WhatsApp Media API error: #{response.body}"
+          FlowChat.logger.error { "WhatsApp::Client: Media API error: #{response.body}" }
           nil
         end
       end
@@ -403,7 +451,7 @@ module FlowChat
         if response.is_a?(Net::HTTPSuccess)
           response.body
         else
-          Rails.logger.error "WhatsApp Media download error: #{response.body}"
+          FlowChat.logger.error { "WhatsApp::Client: Media download error: #{response.body}" }
           nil
         end
       end
@@ -420,7 +468,7 @@ module FlowChat
         response = http.head(uri.path)
         response["content-type"]
       rescue => e
-        Rails.logger.warn "Could not detect MIME type for #{url}: #{e.message}"
+        FlowChat.logger.warn { "WhatsApp::Client: Could not detect MIME type for #{url}: #{e.message}" }
         nil
       end
 
@@ -489,6 +537,13 @@ module FlowChat
           result
         else
           FlowChat.logger.error { "WhatsApp::Client: API request failed - #{response.code}: #{response.body}" }
+          report_api_error(
+            "WhatsApp API request failed",
+            response_code: response.code,
+            response_body: response.body,
+            recipient: to,
+            message_type: message_type
+          )
           nil
         end
       rescue Net::OpenTimeout, Net::ReadTimeout => network_error
@@ -497,9 +552,85 @@ module FlowChat
         raise network_error
       rescue => error
         FlowChat.logger.error { "WhatsApp::Client: API request exception: #{error.class.name}: #{error.message}" }
+        report_api_error(
+          "WhatsApp API request exception: #{error.class.name}",
+          error: error,
+          recipient: to,
+          message_type: message_type
+        )
         nil
       end
 
+      def send_read_receipt_payload(payload, message_id)
+        FlowChat.logger.debug { "WhatsApp::Client: Marking message #{message_id} as read (typing=#{payload.key?(:typing_indicator)})" }
+
+        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
+
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{@config.access_token}"
+        request["Content-Type"] = "application/json"
+        request.body = payload.to_json
+
+        response = http.request(request)
+
+        if response.is_a?(Net::HTTPSuccess)
+          JSON.parse(response.body)
+        else
+          FlowChat.logger.error { "WhatsApp::Client: mark_as_read failed - #{response.code}: #{response.body}" }
+          report_api_error(
+            "WhatsApp mark_as_read failed",
+            response_code: response.code,
+            response_body: response.body,
+            message_type: "read_receipt"
+          )
+          nil
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout => network_error
+        FlowChat.logger.error { "WhatsApp::Client: Network timeout marking read: #{network_error.class.name}: #{network_error.message}" }
+        raise network_error
+      rescue => error
+        FlowChat.logger.error { "WhatsApp::Client: mark_as_read exception: #{error.class.name}: #{error.message}" }
+        report_api_error(
+          "WhatsApp mark_as_read exception: #{error.class.name}",
+          error: error,
+          message_type: "read_receipt"
+        )
+        nil
+      end
+
+      def report_api_error(message, response_code: nil, response_body: nil, error: nil, recipient: nil, message_type: nil)
+        error_details = parse_error_response(response_body)
+
+        FlowChat::Instrumentation.report_api_error(
+          message,
+          error: error,
+          platform: :whatsapp,
+          phone_number_id: @config.phone_number_id,
+          recipient: recipient,
+          message_type: message_type,
+          response_code: response_code,
+          **error_details
+        )
+      end
+
+      def parse_error_response(response_body)
+        return {} unless response_body
+
+        parsed = JSON.parse(response_body)
+        return {} unless parsed.is_a?(Hash) && parsed["error"]
+
+        {
+          error_type: parsed.dig("error", "type"),
+          error_code: parsed.dig("error", "code"),
+          error_subcode: parsed.dig("error", "error_subcode"),
+          error_message: parsed.dig("error", "message")
+        }.compact
+      rescue JSON::ParserError
+        {}
+      end
+
       def send_media_message(to, media_type, url_or_id, caption: nil, filename: nil, mime_type: nil)
         media_object = if url?(url_or_id)
           {link: url_or_id}

data/lib/flow_chat/whatsapp/configuration.rb

@@ -29,7 +29,7 @@ module FlowChat
 
         config = new(nil)
 
-        if defined?(Rails) && Rails.application.credentials.whatsapp
+        if defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.credentials&.whatsapp
           FlowChat.logger.debug { "WhatsApp::Configuration: Loading from Rails credentials" }
           credentials = Rails.application.credentials.whatsapp
           config.access_token = credentials[:access_token]

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

@@ -10,6 +10,7 @@ module FlowChat
     module Gateway
       class CloudApi
         include FlowChat::Instrumentation
+        include FlowChat::GatewayAsyncSupport
 
         attr_reader :context
 
@@ -24,48 +25,59 @@ module FlowChat
 
         def call(context)
           @context = context
-          controller = context.controller
-          request = controller.request
+          @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)
+          # Skip webhook-specific handling in background mode
+          unless in_background?
+            # Handle webhook verification
+            if request.get? && request.params["hub.mode"] == "subscribe"
+              FlowChat.logger.info { "CloudApi: Handling webhook verification request" }
+              return handle_verification(context)
+            end
           end
 
           # Handle webhook messages
           if request.post?
-            FlowChat.logger.info { "CloudApi: Handling webhook message" }
+            FlowChat.logger.info { "CloudApi: Handling webhook message (background: #{in_background?})" }
             return handle_webhook(context)
           end
 
           FlowChat.logger.warn { "CloudApi: Invalid request method or parameters - returning bad request" }
-          controller.head :bad_request
+          @controller.head :bad_request
         end
 
         # Expose client for out-of-band messaging
         attr_reader :client
 
+        # Configure WhatsApp-specific middleware stack
+        def self.configure_middleware_stack(builder, custom_middleware)
+          FlowChat.logger.debug { "CloudApi: Configuring WhatsApp middleware stack" }
+
+          builder.use custom_middleware
+          FlowChat.logger.debug { "CloudApi: Added custom middleware" }
+
+          builder.use FlowChat::Whatsapp::Middleware::ChoiceMapper
+          FlowChat.logger.debug { "CloudApi: Added Whatsapp::Middleware::ChoiceMapper" }
+        end
+
         private
 
         def determine_message_handler(context)
-          # Check if simulator mode was already detected and set in context
+          # Use simulator mode if enabled, otherwise always use inline
           if context["simulator_mode"]
             FlowChat.logger.debug { "CloudApi: Using simulator message handler" }
-            return :simulator
+            :simulator
+          else
+            FlowChat.logger.debug { "CloudApi: Using inline message handler" }
+            :inline
           end
-
-          # Use global WhatsApp configuration
-          mode = FlowChat::Config.whatsapp.message_handling_mode
-          FlowChat.logger.debug { "CloudApi: Using #{mode} message handling mode" }
-          mode
         end
 
         def handle_verification(context)
-          controller = context.controller
-          params = controller.request.params
+          params = @controller.request.params
 
           verify_token = @config.verify_token
           provided_token = params["hub.verify_token"]
@@ -80,7 +92,7 @@ module FlowChat
               platform: :whatsapp
             })
 
-            controller.render plain: challenge
+            @controller.render plain: challenge
           else
             # Use instrumentation for webhook verification failure
             instrument(Events::WEBHOOK_FAILED, {
@@ -88,20 +100,18 @@ module FlowChat
               platform: :whatsapp
             })
 
-            controller.head :forbidden
+            @controller.head :forbidden
           end
         end
 
         def handle_webhook(context)
-          controller = context.controller
-
           # Parse body
           begin
-            parse_request_body(controller.request)
+            parse_request_body(@controller.request)
             FlowChat.logger.debug { "CloudApi: Successfully parsed webhook request body" }
           rescue JSON::ParserError => e
             FlowChat.logger.error { "CloudApi: Failed to parse webhook body: #{e.message}" }
-            return controller.head :bad_request
+            return @controller.head :bad_request
           end
 
           # Check for simulator mode parameter in request (before validation)
@@ -112,10 +122,11 @@ module FlowChat
             context["simulator_mode"] = true
           end
 
-          # Validate webhook signature for security (skip for simulator mode)
-          unless is_simulator_mode || valid_webhook_signature?(controller.request)
-            FlowChat.logger.warn { "CloudApi: Invalid webhook signature received - rejecting request" }
-            return controller.head :unauthorized
+          # Validate webhook signature for security (skip for simulator mode and background)
+          # Return 200 OK even for invalid signatures to prevent WhatsApp from retrying
+          unless in_background? || is_simulator_mode || valid_webhook_signature?(@controller.request)
+            FlowChat.logger.warn { "CloudApi: Invalid webhook signature - dropping request" }
+            return @controller.head :ok
           end
 
           FlowChat.logger.debug { "CloudApi: Webhook signature validation passed" }
@@ -124,19 +135,19 @@ module FlowChat
           entry = @body.dig("entry", 0)
           unless entry
             FlowChat.logger.debug { "CloudApi: No entry found in webhook body - returning OK" }
-            return controller.head :ok
+            return @controller.head :ok
           end
 
           changes = entry.dig("changes", 0)
           unless changes
             FlowChat.logger.debug { "CloudApi: No changes found in webhook entry - returning OK" }
-            return controller.head :ok
+            return @controller.head :ok
           end
 
           value = changes["value"]
           unless value
             FlowChat.logger.debug { "CloudApi: No value found in webhook changes - returning OK" }
-            return controller.head :ok
+            return @controller.head :ok
           end
 
           # Handle incoming messages
@@ -147,15 +158,28 @@ module FlowChat
             phone_number = FlowChat::PhoneNumberUtil.to_e164(message["from"])
             message_id = message["id"]
             contact_name = contact&.dig("profile", "name")
+            business_phone_number = value.dig("metadata", "display_phone_number")
+            business_phone_number_id = value.dig("metadata", "phone_number_id")
+
+            # Validate that webhook is for our configured phone number
+            if business_phone_number_id != @config.phone_number_id
+              FlowChat.logger.warn { "CloudApi: Webhook received for phone_number_id '#{business_phone_number_id}' but configured for '#{@config.phone_number_id}' - rejecting" }
+              return @controller.head :forbidden
+            end
 
             context["request.id"] = phone_number
+            context["request.user_id"] = phone_number
+            context["request.user_name"] = contact_name if contact_name
             context["request.msisdn"] = phone_number
-            context["request.user_id"] = context["request.msisdn"]
             context["request.gateway"] = :whatsapp_cloud_api
             context["request.platform"] = :whatsapp
             context["request.message_id"] = message_id
-            context["request.contact_name"] = contact_name
-            context["request.timestamp"] = message["timestamp"]
+            context["request.timestamp"] = Time.current.iso8601
+            context["request.body"] = @body
+
+            context["whatsapp.business.phone_number"] = FlowChat::PhoneNumberUtil.to_e164(business_phone_number)
+            context["whatsapp.business.phone_number_id"] = business_phone_number_id
+            context["whatsapp.client"] = @client
 
             # Extract message content based on type
             extract_message_content!(message, context)
@@ -166,25 +190,30 @@ module FlowChat
                 from: phone_number,
                 message: context.input,
                 message_type: message["type"],
-                message_id: message_id,
+                message_id: message_id
               })
             end
 
-
             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
-            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)
+            # Determine routing: async enqueue, background execute, or inline
+            if should_enqueue_async?
+              # Webhook with async enabled → enqueue job and return immediately
+              enqueue_async_job
+              return @controller.head :ok
+            else
+              # Background OR inline → process message
+              # Determine message handling mode (simulator vs inline)
+              handler_mode = determine_message_handler(context)
+
+              # Process the message based on handling mode
+              case handler_mode
+              when :inline
+                handle_message_inline(context, @controller)
+              when :simulator
+                # Return early from simulator mode to preserve the JSON response
+                return handle_message_simulator(context, @controller)
+              end
             end
           end
 
@@ -195,7 +224,7 @@ module FlowChat
             FlowChat.logger.debug { "CloudApi: Status updates: #{statuses.inspect}" }
           end
 
-          controller.head :ok
+          @controller.head :ok
         end
 
         # Validate webhook signature to ensure request comes from WhatsApp
@@ -269,7 +298,7 @@ module FlowChat
           case message_type
           when "text"
             content = message.dig("text", "body")
-            context.input = content
+            context.input = content.presence || ""
             FlowChat.logger.debug { "CloudApi: Text message content: '#{content}'" }
           when "interactive"
             # Handle button/list replies
@@ -290,57 +319,57 @@ module FlowChat
               address: message.dig("location", "address")
             }
             context["request.location"] = location
-            context.input = "$location$"
+            context.input = FlowChat::Input::LOCATION
             FlowChat.logger.debug { "CloudApi: Location received - Lat: #{location[:latitude]}, Lng: #{location[:longitude]}" }
-          when "image", "document", "audio", "video"
+          when "image", "document", "audio", "video", "sticker"
+            media_data = message[message["type"]]
             context["request.media"] = {
-              type: message["type"],
-              id: message.dig(message["type"], "id"),
-              mime_type: message.dig(message["type"], "mime_type"),
-              caption: message.dig(message["type"], "caption")
+              type: message["type"].to_sym,
+              id: media_data["id"],
+              mime_type: media_data["mime_type"],
+              caption: media_data["caption"],
+              filename: media_data["filename"],
+              sha256: media_data["sha256"],
+              animated: media_data["animated"]
             }
-            context.input = "$media$"
+            context.input = FlowChat::Input::MEDIA
+            FlowChat.logger.debug { "CloudApi: Media received - Type: #{message["type"]}, ID: #{media_data["id"]}" }
+          when "contacts"
+            # WhatsApp sends contacts as an array, take the first one
+            contact_data = message.dig("contacts", 0)
+            if contact_data
+              phones = contact_data.dig("phones") || []
+              context["request.contact"] = {
+                name: contact_data.dig("name", "formatted_name"),
+                first_name: contact_data.dig("name", "first_name"),
+                last_name: contact_data.dig("name", "last_name"),
+                phones: phones.map { |p| p["phone"] },
+                phone_number: phones.first&.dig("phone")
+              }
+              context.input = FlowChat::Input::CONTACT
+              FlowChat.logger.debug { "CloudApi: Contact received - Name: #{context["request.contact"][:name]}" }
+            end
           end
         end
 
         def handle_message_inline(context, controller)
           response = @app.call(context)
           if response
-            _type, prompt, choices, media = response
-            rendered_message = render_response(prompt, choices, media)
-            result = @client.send_message(context["request.msisdn"], rendered_message)
+            type, prompt, choices, media = response
+            result = @client.send_message(context["request.msisdn"], prompt, choices: choices, media: media)
             context["whatsapp.message_result"] = result
-          end
-        end
 
-        def handle_message_background(context, controller)
-          # Process the flow synchronously (maintaining controller context)
-          response = @app.call(context)
-
-          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"],
-              response: rendered_message,
-              config_name: @config.name
-            }
-
-            # Get job class from configuration
-            job_class_name = FlowChat::Config.whatsapp.background_job_class
-
-            # Enqueue background job for sending only
-            begin
-              job_class = job_class_name.constantize
-              job_class.perform_later(send_data)
-            rescue NameError
-              # Fallback to inline sending if no job system
-              Rails.logger.warn "Background mode requested but no #{job_class_name} found. Falling back to inline sending."
-              result = @client.send_message(context["request.msisdn"], rendered_message)
-              context["whatsapp.message_result"] = result
-            end
+            # Instrument message sent
+            instrument(Events::MESSAGE_SENT, {
+              to: context["request.msisdn"],
+              session_id: context["request.id"],
+              message: prompt,
+              message_type: (type == :prompt) ? "prompt" : "terminal",
+              gateway: :whatsapp_cloud_api,
+              platform: :whatsapp,
+              content_length: prompt.to_s.length,
+              timestamp: context["request.timestamp"]
+            })
           end
         end
 
@@ -348,12 +377,12 @@ module FlowChat
           response = @app.call(context)
 
           if response
-            _type, prompt, choices, media = response
-            rendered_message = render_response(prompt, choices, media)
+            _, prompt, choices, media = response
+            response_data = 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"])
+            message_payload = @client.build_message_payload(response_data, context["request.msisdn"])
 
             simulator_response = {
               mode: "simulator",
@@ -361,7 +390,7 @@ module FlowChat
               would_send: message_payload,
               message_info: {
                 to: context["request.msisdn"],
-                contact_name: context["request.contact_name"],
+                contact_name: context["request.user_name"],
                 timestamp: Time.now.iso8601
               }
             }
@@ -384,8 +413,7 @@ module FlowChat
           return false unless simulator_secret && !simulator_secret.empty?
 
           # Check for simulator cookie
-          request = context.controller.request
-          simulator_cookie = request.cookies["flowchat_simulator"]
+          simulator_cookie = @controller.request.cookies["flowchat_simulator"]
           return false unless simulator_cookie
 
           # Verify the cookie is a valid HMAC signature
@@ -412,7 +440,15 @@ module FlowChat
         end
 
         def parse_request_body(request)
-          @body ||= JSON.parse(request.body.read)
+          return @body if @body
+
+          if request.body.nil?
+            FlowChat.logger.debug { "CloudApi: Request body is nil, returning empty hash" }
+            @body = {}
+          else
+            request.body.rewind if request.body.respond_to?(:rewind)
+            @body = JSON.parse(request.body.read)
+          end
         end
 
         def render_response(prompt, choices, media)