flow_chat 0.8.2 → 0.10.0

data/lib/flow_chat/ussd/gateway/nalo.rb

@@ -3,6 +3,7 @@ module FlowChat
     module Gateway
       class Nalo
         include FlowChat::Instrumentation
+        include FlowChat::GatewayAsyncSupport
 
         attr_reader :context
 
@@ -10,9 +11,15 @@ module FlowChat
           @app = app
         end
 
+        # USSD does not support async processing due to synchronous protocol requirements
+        def async_supported?
+          false
+        end
+
         def call(context)
           @context = context
-          params = context.controller.request.params
+          @controller = context.controller
+          params = @controller.request.params
 
           context["request.id"] = params["USERID"]
           context["request.msisdn"] = FlowChat::PhoneNumberUtil.to_e164(params["MSISDN"])
@@ -21,9 +28,9 @@ module FlowChat
           context["request.timestamp"] = Time.current.iso8601
           context["request.gateway"] = :nalo
           context["request.platform"] = :ussd
-          context["request.network"] = nil
+          context["request.body"] = (params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h).transform_keys(&:to_s)
           # context["request.type"] = params["MSGTYPE"] ? :initial : :response
-          context.input = params["USERDATA"].presence
+          context.input = params["USERDATA"].presence || ""
 
           # Instrument message received when user provides input using new scalable approach
           if context.input.present?
@@ -49,7 +56,7 @@ module FlowChat
             timestamp: context["request.timestamp"]
           })
 
-          context.controller.render json: {
+          @controller.render json: {
             USERID: params["USERID"],
             MSISDN: params["MSISDN"],
             MSG: render_prompt(prompt, choices, media),
@@ -57,6 +64,19 @@ module FlowChat
           }
         end
 
+        def self.configure_middleware_stack(builder, custom_middleware)
+          FlowChat.logger.debug { "FlowChat::Ussd::Gateway::Nalo: Configuring middleware stack" }
+
+          builder.use FlowChat::Ussd::Middleware::Pagination
+          FlowChat.logger.debug { "FlowChat::Ussd::Gateway::Nalo: Added Ussd::Middleware::Pagination" }
+
+          builder.use custom_middleware
+          FlowChat.logger.debug { "FlowChat::Ussd::Gateway::Nalo: Added custom middleware" }
+
+          builder.use FlowChat::Ussd::Middleware::ChoiceMapper
+          FlowChat.logger.debug { "FlowChat::Ussd::Gateway::Nalo: Added Ussd::Middleware::ChoiceMapper" }
+        end
+
         private
 
         def render_prompt(prompt, choices, media)

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

@@ -57,6 +57,16 @@ module FlowChat
           @context.input = original_choice
         end
 
+        # USSD is deliberately exempt from the fold every other choice mapper
+        # now takes. A numeric keypad can only ever send a position, and
+        # positions are unique by construction, so the relation this resolves
+        # on is already injective - there is no equivalence under which two
+        # choices could collapse into one another.
+        #
+        # Every other mapper has to be *given* that guarantee, by asking
+        # FlowChat::ChoiceTitles to number a set whose titles collide under
+        # its own resolver's fold. Nothing here needs to, and adding aliasing
+        # to this mapper would introduce the very ambiguity it does not have.
         def create_numbered_mapping(choices)
           # Choices are always a hash after normalize_choices
           numbered_choices = {}

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

@@ -21,7 +21,6 @@ module FlowChat
           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?
@@ -41,8 +40,8 @@ module FlowChat
               end
             end
 
-            [type, prompt, []]
           end
+          [type, prompt, []]
         end
 
         private
@@ -61,15 +60,17 @@ module FlowChat
 
         def handle_intercepted_request
           FlowChat.logger.info { "Ussd::Pagination: Handling paginated request" }
-          start, finish, has_more = calculate_offsets
+          # Cache current_page to avoid multiple calculations
+          page = current_page
+          start, finish, has_more = calculate_offsets_for_page(page)
           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)
+          set_pagination_state(page, start, finish)
 
           # Instrument pagination navigation
           instrument(Events::PAGINATION_TRIGGERED, {
             session_id: @context["session.id"],
-            current_page: current_page,
+            current_page: page,
             total_pages: calculate_total_pages,
             content_length: pagination_state["prompt"].length,
             page_limit: FlowChat::Config.ussd.pagination_page_size,
@@ -113,7 +114,10 @@ module FlowChat
 
         def calculate_offsets
           page = current_page
+          calculate_offsets_for_page(page)
+        end
 
+        def calculate_offsets_for_page(page)
           FlowChat.logger.debug { "Ussd::Pagination: Calculating offsets for page #{page}" }
 
           offset = pagination_state["offsets"][page.to_s]

data/lib/flow_chat/ussd/renderer.rb

@@ -27,7 +27,7 @@ module FlowChat
       def build_media
         return unless media.present?
 
-        media_url = media[:url] || media[:path]
+        media_url = media[:url]
         media_type = media[:type] || :image
 
         # For USSD, we append the media URL to the message

data/lib/flow_chat/version.rb

@@ -1,3 +1,3 @@
 module FlowChat
-  VERSION = "0.8.2"
+  VERSION = "0.10.0"
 end

data/lib/flow_chat/whatsapp/client.rb

@@ -19,17 +19,27 @@ 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)}'" }
-
-        result = instrument(Events::MESSAGE_SENT, {
-          to: to,
-          message_type: type.to_s,
-          content_length: content.to_s.length,
-          platform: :whatsapp
-        }) do
+      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
+        _, _, options = response
+
+        # MESSAGE_SENT is instrumented by the gateway, not here. This wrapped
+        # the send in its own instrument block, and ActiveSupport::Notifications
+        # publishes a block event once the block returns whatever it returned -
+        # so the event fired even when the send had failed and this method was
+        # about to answer nil, and fired a second time when the gateway
+        # instrumented the same send. Every subscriber counted a successful
+        # send twice and a failed one once.
+        result = begin
+          # Above the button cap there is no interactive surface that can
+          # carry media (see the renderer), so it rides in options[:media]
+          # and goes out as its own message ahead of the choice message.
+          send_message_payload(build_message_payload(options[:media], to)) if options[:media]
+
           message_data = build_message_payload(response, to)
           send_message_payload(message_data)
         end
@@ -50,7 +60,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 +70,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 +83,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 +96,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 +113,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 +165,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 +434,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 +458,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 +475,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 +544,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 +559,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

@@ -1,12 +1,16 @@
 module FlowChat
   module Whatsapp
     class Configuration
+      include FlowChat::NamedConfiguration
+
+      # "Whatsapp" is the constant, "WhatsApp" is the product.
+      def self.configuration_label
+        "WhatsApp"
+      end
+
       attr_accessor :access_token, :phone_number_id, :verify_token, :app_id, :app_secret,
         :webhook_verify_token, :business_account_id, :name, :skip_signature_validation
 
-      # Class-level storage for named configurations
-      @@configurations = {}
-
       def initialize(name)
         @name = name
         @access_token = nil
@@ -29,7 +33,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]
@@ -60,56 +64,13 @@ module FlowChat
         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)
-        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)
-        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
-        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?
-        is_valid = access_token && !access_token.to_s.empty? &&
+        # Wrapped so a predicate answers true or false rather than nil, which
+        # the bare && chain returns for a missing first field. Intercom and
+        # Telegram already do this and pin it in their tests.
+        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?
+          verify_token && !verify_token.to_s.empty?)
 
         FlowChat.logger.debug { "WhatsApp::Configuration: Configuration valid: #{is_valid}" }
         is_valid

data/lib/flow_chat/whatsapp/configuration_error.rb

@@ -0,0 +1,9 @@
+module FlowChat
+  module Whatsapp
+    # Its own file so Zeitwerk can resolve it by name. Declared inside
+    # gateway/cloud_api.rb, which Zeitwerk maps to a different constant, it existed only
+    # once that file had loaded for some other reason, so an application
+    # rescuing it, or a test naming it first, got an uninitialized constant.
+    class ConfigurationError < StandardError; end
+  end
+end