flow_chat 0.9.0 → 0.10.1

data/lib/flow_chat/instagram/gateway/send_api.rb

@@ -0,0 +1,63 @@
+module FlowChat
+  module Instagram
+    module Gateway
+      # Instagram DMs, on the shared Messenger Platform envelope.
+      #
+      # A sibling of the Messenger gateway rather than a subclass of it: the
+      # two differ in credentials, limits and subscription object, and
+      # neither owns the other.
+      class SendApi < FlowChat::Meta::MessagingGateway
+        def platform
+          :instagram
+        end
+
+        def gateway_name
+          :instagram_send_api
+        end
+
+        def configuration_class
+          FlowChat::Instagram::Configuration
+        end
+
+        def client_class
+          FlowChat::Instagram::Client
+        end
+
+        def renderer_class
+          FlowChat::Instagram::Renderer
+        end
+
+        def self.choice_mapper_class
+          FlowChat::Instagram::Middleware::ChoiceMapper
+        end
+
+        # Confirmed against a live delivery for a page-linked account: Meta's
+        # docs are ambiguous about whether these arrive under "page" or
+        # "instagram", and they arrive under "instagram". The delivery named
+        # the Instagram professional account in entry.id, not the linked Page,
+        # which is what webhook_account_id encodes.
+        FACEBOOK_LOGIN_WEBHOOK_OBJECT = "instagram"
+
+        # Kept as its own constant rather than sharing one with the path above:
+        # the two integrations are configured independently in Meta's
+        # dashboard, so a correction to one path's value must not silently
+        # change the other's.
+        INSTAGRAM_LOGIN_WEBHOOK_OBJECT = "instagram"
+
+        def expected_webhook_object
+          (@config.login == :instagram) ? INSTAGRAM_LOGIN_WEBHOOK_OBJECT : FACEBOOK_LOGIN_WEBHOOK_OBJECT
+        end
+
+        private
+
+        def configuration_error_class
+          FlowChat::Instagram::ConfigurationError
+        end
+
+        def platform_label
+          "Instagram"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+module FlowChat
+  module Instagram
+    module Middleware
+      class ChoiceMapper < FlowChat::Messenger::Middleware::ChoiceMapper
+        ID_KEY = "instagram.choice_mapping"
+        POSITION_KEY = "instagram.position_mapping"
+
+        private
+
+        def platform_limits
+          FlowChat::Config.instagram
+        end
+
+        # The body always carries numbers here, so a typed number must
+        # always resolve, not only above the carousel capacity.
+        def always_number?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/instagram/renderer.rb

@@ -0,0 +1,23 @@
+module FlowChat
+  module Instagram
+    # Instagram's ladder is Messenger's algorithm with different constants.
+    # The gateways are siblings (Instagram's does not depend on Messenger's),
+    # but the renderers really are the same shape, so this is the one place
+    # Instagram inherits from Messenger rather than mirroring it.
+    class Renderer < FlowChat::Messenger::Renderer
+      private
+
+      def limits
+        FlowChat::Config.instagram
+      end
+
+      # Quick replies and carousels are mobile only on Instagram, so the
+      # options are always listed in the body as well. A user on desktop
+      # sees the prompt and nothing tappable, and without the list has no
+      # way to reply at all.
+      def always_number?
+        true
+      end
+    end
+  end
+end

data/lib/flow_chat/instrumentation/metrics_collector.rb

@@ -82,7 +82,12 @@ module FlowChat
           if event.payload[:message_type]
             increment_counter("#{platform}.messages.sent.by_type.#{event.payload[:message_type]}")
           end
-          track_timing("#{platform}.api.response_time", event.duration)
+          # The gateway measures the send itself and puts it on the payload.
+          # event.duration would read as zero here: MESSAGE_SENT is published
+          # after the send returns, rather than wrapped around it, because a
+          # wrapped event fires whatever the block returned - including for
+          # sends the platform refused.
+          track_timing("#{platform}.api.response_time", event.payload[:duration_ms] || event.duration)
         end
 
         ActiveSupport::Notifications.subscribe("webhook.verified.flow_chat") do |event|

data/lib/flow_chat/instrumentation.rb

@@ -4,6 +4,20 @@ module FlowChat
   module Instrumentation
     extend ActiveSupport::Concern
 
+    # Where a delivered reply's platform message id is left on the context, the
+    # same way for every gateway. nil when the platform does not name one.
+    DELIVERED_MESSAGE_ID_KEY = "delivery.platform_message_id"
+
+    # How long the send itself took, in milliseconds, left here by
+    # report_delivery_failure for the gateway to put on MESSAGE_SENT.
+    #
+    # Measured rather than taken from ActiveSupport::Notifications' own event
+    # duration: a block event is published whatever the block returns, so
+    # timing the send that way meant publishing MESSAGE_SENT for sends that
+    # failed. The event is emitted after the fact instead, which leaves its
+    # own duration at zero, so the real figure is carried in the payload.
+    DELIVERY_DURATION_KEY = "delivery.duration_ms"
+
     # Instrument a block of code with the given event name and payload
     def instrument(event_name, payload = {}, &block)
       enriched_payload = payload&.dup || {}
@@ -18,6 +32,122 @@ module FlowChat
       self.class.instrument(event_name, enriched_payload, &block)
     end
 
+    # Wraps a delivery so a reply the platform would not take is reported.
+    #
+    # A gateway sends after the middleware stack has returned. An app that
+    # records what the flow said has therefore already recorded it, and
+    # recorded it as having gone out, before anything knows whether it did.
+    # The send is the only place that learns otherwise, and it is downstream of
+    # everything that could act on it.
+    #
+    # Reported two ways, because two different kinds of reader want it.
+    #
+    # The event is a broadcast, and takes the same shape its gateway gives
+    # MESSAGE_SENT: what was being sent and where, and nothing else. Anyone may
+    # subscribe, including tools that write whatever they are handed straight
+    # into a log, so it carries no more than the send itself already announces.
+    #
+    # The callback is the app that owns this turn, acting on records only it
+    # knows about. It gets the whole context because it is the app's own code,
+    # configured by the app, and reading what the app put there. That is not
+    # true of a subscriber, and the context holds the gateway client and the
+    # raw inbound body.
+    #
+    # Re-raises whatever the send raised: this reports a failure, it does not
+    # handle one.
+    # A send fails two ways and only one of them raises. Every client here answers
+    # with the platform's parsed response when the message was accepted and nil
+    # once it has already logged an API error, so a nil result is a failure that
+    # arrived quietly. Treating it as success fired on_delivery_success for a
+    # message that was never delivered, and stamped a nil id onto the context as
+    # though the platform had named one.
+    #
+    # It reports rather than raises, because the client already decided not to:
+    # turning a swallowed API error into an exception here would fail the webhook
+    # for a reply the platform merely declined.
+    def report_delivery_failure(context, **payload)
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = yield
+      context[DELIVERY_DURATION_KEY] = elapsed_ms_since(started_at)
+
+      if result.nil?
+        error = FlowChat::DeliveryError.new("#{payload[:platform] || "the platform"} did not accept the message")
+        report_to_subscribers(error, payload)
+        report_to_app(context, error)
+        return nil
+      end
+
+      report_delivery_success(context, result)
+      result
+    rescue => error
+      context[DELIVERY_DURATION_KEY] ||= elapsed_ms_since(started_at) if started_at
+      report_to_subscribers(error, payload)
+      report_to_app(context, error)
+      raise error
+    end
+
+    def elapsed_ms_since(started_at)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(2)
+    end
+
+    # The success half. Runs where the send happened, which is the only place that
+    # knows what the platform called the message.
+    def report_delivery_success(context, result)
+      context[DELIVERED_MESSAGE_ID_KEY] = platform_message_id_from(result)
+      FlowChat::Config.on_delivery_success&.call(context, result)
+    rescue => callback_error
+      FlowChat.logger.error do
+        "Instrumentation: on_delivery_success raised #{callback_error.class}: #{callback_error.message}"
+      end
+    end
+
+    # What the platform called the message it just accepted.
+    #
+    # Overridden by every gateway that delivers out of band, because each one is
+    # the only thing that knows the shape of its own client's answer. Naming it
+    # here rather than in each app is the point: an app stamping the id onto its
+    # own record should not have to carry a case statement over platforms.
+    def platform_message_id_from(result)
+      nil
+    end
+
+    # Neither reader may replace the delivery error with one of its own, which
+    # would hide the failure they are being told about. Notifications gather
+    # subscriber errors and re-raise them, so both are reachable.
+    def report_to_subscribers(error, payload)
+      instrument(Events::MESSAGE_DELIVERY_FAILED, payload.merge(
+        error_class: error.class.name,
+        message: error.message
+      ))
+    rescue => subscriber_error
+      FlowChat.logger.error do
+        "Instrumentation: a #{Events::MESSAGE_DELIVERY_FAILED} subscriber raised " \
+          "#{subscriber_error.class}: #{subscriber_error.message}"
+      end
+    end
+
+    def report_to_app(context, error)
+      FlowChat::Config.on_delivery_failure&.call(context, error)
+    rescue => callback_error
+      FlowChat.logger.error do
+        "Instrumentation: on_delivery_failure raised #{callback_error.class}: #{callback_error.message}"
+      end
+    end
+
+    # True when this turn carries something to process — text OR a structured
+    # attachment (media/location/contact). Gateways gate MESSAGE_RECEIVED on this
+    # so caption-less media, locations, and contacts are still instrumented: they
+    # set a blank input string (not the old "$media$"-style sentinel), so a plain
+    # `context.input.present?` check would silently drop them.
+    def inbound_message?(context)
+      return false unless context
+
+      context.input.present? ||
+        !context["request.media"].nil? ||
+        !context["request.location"].nil? ||
+        !context["request.contact"].nil?
+    end
+
     class_methods do
       def instrument(event_name, payload = {}, &block)
         FlowChat::Instrumentation.instrument(event_name, payload, &block)
@@ -36,12 +166,25 @@ module FlowChat
     end
 
     # Shared helper for reporting API errors with instrumentation and Rails.error
-    # @param message [String] Error message
+    #
+    # `message` is prose for a human reading logs. Subscribers deciding what to
+    # do about an error should read the structured keys instead, so that
+    # rewording a message never changes behaviour somewhere else:
+    #
+    #   error_class  the exception's class, filled in here from `error`
+    #   error_type   what kind of failure it is, named by the adapter
+    #   error_code   the platform's own code, where it gives one
+    #
+    # @param message [String] Human readable description, for logs
     # @param error [Exception, nil] Original exception if available
     # @param context [Hash] Platform-specific error context (must include :platform)
     def self.report_api_error(message, error: nil, **context)
       error_context = context.compact
 
+      # An exception's class is a classification the caller already made. Carry
+      # it so a subscriber can branch on it rather than parsing the message.
+      error_context[:error_class] ||= error.class.name if error
+
       # Instrument for custom subscribers
       instrument(Events::API_ERROR, error_context.merge(message: message))
 
@@ -74,6 +217,13 @@ module FlowChat
       # Gateway/platform information is included in the payload
       MESSAGE_RECEIVED = "message.received"
       MESSAGE_SENT = "message.sent"
+      # A reply the flow produced that the platform would not take. Carries
+      # what its gateway gives MESSAGE_SENT, plus the error, so a subscriber
+      # sees the same send it would have seen succeed.
+      MESSAGE_DELIVERY_FAILED = "message.delivery_failed"
+      # A platform's own report of what became of a message we sent. Informational:
+      # the send already succeeded or failed at the API call.
+      MESSAGE_STATUS = "message.status"
       WEBHOOK_VERIFIED = "webhook.verified"
       WEBHOOK_FAILED = "webhook.failed"
       API_REQUEST = "api.request"
@@ -86,6 +236,15 @@ module FlowChat
       MIDDLEWARE_BEFORE = "middleware.before"
       MIDDLEWARE_AFTER = "middleware.after"
 
+      # A webhook this gateway verified but does not model, handed on whole.
+      #
+      # FlowChat's job is messaging: inbound turns, the replies they produce, and
+      # what became of them. A platform sends far more than that, and what an
+      # account ban, a contact sync or an imported history means belongs to the
+      # application, not here. Rather than grow a handler per field, the payload is
+      # published with the field that named it, for an application to dispatch on.
+      WEBHOOK_RECEIVED = "webhook.received"
+
       # Conversation management events (for Intercom and similar platforms)
       CONVERSATION_ASSIGNED = "conversation.assigned"
       CONVERSATION_TAGGED = "conversation.tagged"

data/lib/flow_chat/intercom/client.rb

@@ -4,9 +4,6 @@ require "reverse_markdown"
 
 module FlowChat
   module Intercom
-    # Configuration-related errors
-    class ConfigurationError < StandardError; end
-
     # Rate limiting error
     class RateLimitError < StandardError
       attr_reader :retry_after
@@ -49,14 +46,16 @@ module FlowChat
 
         # Use renderer to convert to structured response
         response = FlowChat::Intercom::Renderer.new(prompt, choices: choices, media: media).render
-        type, content, _ = response
-
-        result = instrument(Events::MESSAGE_SENT, {
-          to: conversation_id,
-          message_type: type.to_s,
-          content_length: content.to_s.length,
-          platform: :intercom
-        }) do
+        type, content, options = response
+        attachment_urls = options[:attachment_urls]
+
+        # 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.
+        result = begin
           # Determine message type based on response type
           message_type = case type
           when :note
@@ -65,14 +64,17 @@ module FlowChat
             "comment"
           end
 
-          # Send using official gem
-          reply = intercom.conversations.reply(
+          reply_data = {
             id: conversation_id,
             type: "admin",
             admin_id: @config.admin_id.to_s,
             message_type: message_type,
             body: content.to_s
-          )
+          }
+          reply_data[:attachment_urls] = attachment_urls if attachment_urls
+
+          # Send using official gem
+          reply = intercom.conversations.reply(reply_data)
 
           reply.to_hash
         end
@@ -87,11 +89,13 @@ module FlowChat
         result
       rescue ::Intercom::ResourceNotFound => e
         FlowChat.logger.error { "Intercom::Client: Conversation not found: #{e.message}" }
-        report_api_error("Intercom conversation not found", error: e, conversation_id: conversation_id)
+        report_api_error("Intercom conversation not found", error: e, error_type: "resource_not_found",
+          conversation_id: conversation_id)
         nil
       rescue ::Intercom::AuthenticationError => e
         FlowChat.logger.error { "Intercom::Client: Authentication failed - check access token" }
-        report_api_error("Intercom authentication failed", error: e, conversation_id: conversation_id)
+        report_api_error("Intercom authentication failed", error: e, error_type: "authentication",
+          conversation_id: conversation_id)
         raise ConfigurationError, "Invalid Intercom access token"
       rescue ::Intercom::RateLimitExceeded
         retry_after = 60
@@ -99,7 +103,8 @@ module FlowChat
         raise RateLimitError.new("Intercom API rate limit exceeded", retry_after)
       rescue ::Intercom::ServerError => e
         FlowChat.logger.error { "Intercom::Client: Server error: #{e.message}" }
-        report_api_error("Intercom server error", error: e, conversation_id: conversation_id)
+        report_api_error("Intercom server error", error: e, error_type: "server_error",
+          conversation_id: conversation_id)
         nil
       rescue => e
         FlowChat.logger.error { "Intercom::Client: API request exception: #{e.class.name}: #{e.message}" }
@@ -110,16 +115,9 @@ module FlowChat
       # Build reply payload for Intercom API
       # This method is exposed so the gateway can use it for simulator mode
       def build_reply_payload(response, conversation_id)
-        type, content, _ = response
+        type, content, options = response
 
-        case type
-        when :text
-          {
-            message_type: "comment",
-            type: "admin",
-            admin_id: @config.admin_id.to_s,
-            body: content.to_s
-          }
+        payload = case type
         when :note
           {
             message_type: "note",
@@ -128,7 +126,7 @@ module FlowChat
             body: content.to_s
           }
         else
-          # Default to comment
+          # :text and anything else default to comment
           {
             message_type: "comment",
             type: "admin",
@@ -136,16 +134,24 @@ module FlowChat
             body: content.to_s
           }
         end
+
+        payload[:attachment_urls] = options[:attachment_urls] if options[:attachment_urls]
+        payload
       end
 
       private
 
-      def report_api_error(message, error: nil, conversation_id: nil)
+      # The Intercom gem raises a distinct class per failure and carries the
+      # HTTP status on it. Both say more than the message does, so pass them on
+      # rather than leaving a subscriber to read prose.
+      def report_api_error(message, error: nil, error_type: nil, conversation_id: nil)
         FlowChat::Instrumentation.report_api_error(
           message,
           error: error,
           platform: :intercom,
           app_id: @app_id,
+          error_type: error_type,
+          error_code: (error.http_code if error.is_a?(::Intercom::IntercomError)),
           conversation_id: conversation_id,
           admin_id: @config.admin_id
         )

data/lib/flow_chat/intercom/configuration.rb

@@ -1,10 +1,9 @@
 module FlowChat
   module Intercom
     class Configuration
-      attr_accessor :access_token, :client_secret, :admin_id, :name, :skip_signature_validation
+      include FlowChat::NamedConfiguration
 
-      # Class-level storage for named configurations
-      @@configurations = {}
+      attr_accessor :access_token, :client_secret, :admin_id, :name, :skip_signature_validation
 
       def initialize(name)
         @name = name
@@ -49,52 +48,6 @@ module FlowChat
         config
       end
 
-      # Register a named configuration
-      def self.register(name, config)
-        FlowChat.logger.debug { "Intercom::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 { "Intercom::Configuration: Retrieved configuration '#{name}'" }
-          config
-        else
-          FlowChat.logger.error { "Intercom::Configuration: Configuration '#{name}' not found" }
-          raise ArgumentError, "Intercom 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 { "Intercom::Configuration: Configuration '#{name}' exists: #{exists}" }
-        exists
-      end
-
-      # Get all configuration names
-      def self.configuration_names
-        names = @@configurations.keys
-        FlowChat.logger.debug { "Intercom::Configuration: Available configurations: #{names}" }
-        names
-      end
-
-      # Clear all registered configurations (useful for testing)
-      def self.clear_all!
-        FlowChat.logger.debug { "Intercom::Configuration: Clearing all registered configurations" }
-        @@configurations.clear
-      end
-
-      # Register this configuration with a name
-      def register_as(name)
-        FlowChat.logger.debug { "Intercom::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? && admin_id && !admin_id.to_s.empty?)
 

data/lib/flow_chat/intercom/configuration_error.rb

@@ -0,0 +1,9 @@
+module FlowChat
+  module Intercom
+    # Its own file so Zeitwerk can resolve it by name. Declared inside
+    # client.rb and gateway/intercom_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