flow_chat 0.8.2 → 0.10.0

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/setup.rb

@@ -2,7 +2,7 @@ module FlowChat
   module Instrumentation
     module Setup
       class << self
-        attr_accessor :log_subscriber, :metrics_collector
+        attr_accessor :log_subscriber
 
         # Initialize instrumentation with default subscribers
         def initialize!

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)
@@ -35,6 +165,36 @@ module FlowChat
       ActiveSupport::Notifications.instrument(full_event_name, enriched_payload, &block)
     end
 
+    # Shared helper for reporting API errors with instrumentation and Rails.error
+    #
+    # `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))
+
+      # Report to Rails.error if available
+      if defined?(Rails) && Rails.respond_to?(:error) && Rails.error.respond_to?(:report)
+        exception = error || StandardError.new(message)
+        Rails.error.report(exception, handled: true, context: error_context)
+      end
+    end
+
     # Predefined event names for consistency
     module Events
       # Core framework events
@@ -57,16 +217,38 @@ 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"
       MEDIA_UPLOAD = "media.upload"
+      API_ERROR = "api.error"
 
       PAGINATION_TRIGGERED = "pagination.triggered"
 
       # Middleware events
       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"
+      CONVERSATION_STATE_CHANGED = "conversation.state_changed"
     end
   end
 end

data/lib/flow_chat/intercom/client.rb

@@ -0,0 +1,161 @@
+require "intercom"
+require "json"
+require "reverse_markdown"
+
+module FlowChat
+  module Intercom
+    # Rate limiting error
+    class RateLimitError < StandardError
+      attr_reader :retry_after
+
+      def initialize(message, retry_after = nil)
+        super(message)
+        @retry_after = retry_after
+      end
+    end
+
+    class Client
+      include FlowChat::Instrumentation
+
+      attr_reader :intercom
+      attr_accessor :app_id
+
+      # Convert HTML from Intercom messages to Markdown
+      def self.parse_html(html)
+        ReverseMarkdown.convert(html.to_s).strip.presence || ""
+      end
+
+      def parse_message(html)
+        self.class.parse_html(html)
+      end
+
+      def initialize(config)
+        @config = config
+        @intercom = ::Intercom::Client.new(token: @config.access_token)
+        FlowChat.logger.info { "Intercom::Client: Initialized Intercom client" }
+        FlowChat.logger.debug { "Intercom::Client: API base URL: #{@config.api_base_url}" }
+      end
+
+      # Send a reply to a conversation
+      # @param conversation_id [String] Conversation ID
+      # @param response [Array] FlowChat response array [type, content, options]
+      # @return [Hash] API response or nil on error
+      def send_message(conversation_id, prompt, choices: nil, media: nil)
+        FlowChat.logger.info { "Intercom::Client: Sending message to conversation #{conversation_id}" }
+        FlowChat.logger.debug { "Intercom::Client: Message content: '#{prompt.to_s.truncate(100)}'" }
+
+        # Use renderer to convert to structured response
+        response = FlowChat::Intercom::Renderer.new(prompt, choices: choices, media: media).render
+        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
+            "note"
+          else
+            "comment"
+          end
+
+          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
+
+        if result
+          message_id = result["id"]
+          FlowChat.logger.debug { "Intercom::Client: Message sent successfully to conversation #{conversation_id}, message_id: #{message_id}" }
+        else
+          FlowChat.logger.error { "Intercom::Client: Failed to send message to conversation #{conversation_id}" }
+        end
+
+        result
+      rescue ::Intercom::ResourceNotFound => e
+        FlowChat.logger.error { "Intercom::Client: Conversation not found: #{e.message}" }
+        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, error_type: "authentication",
+          conversation_id: conversation_id)
+        raise ConfigurationError, "Invalid Intercom access token"
+      rescue ::Intercom::RateLimitExceeded
+        retry_after = 60
+        FlowChat.logger.warn { "Intercom::Client: Rate limit exceeded - retry after #{retry_after}s" }
+        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, error_type: "server_error",
+          conversation_id: conversation_id)
+        nil
+      rescue => e
+        FlowChat.logger.error { "Intercom::Client: API request exception: #{e.class.name}: #{e.message}" }
+        report_api_error("Intercom API request exception: #{e.class.name}", error: e, conversation_id: conversation_id)
+        nil
+      end
+
+      # 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, options = response
+
+        payload = case type
+        when :note
+          {
+            message_type: "note",
+            type: "admin",
+            admin_id: @config.admin_id.to_s,
+            body: content.to_s
+          }
+        else
+          # :text and anything else default to comment
+          {
+            message_type: "comment",
+            type: "admin",
+            admin_id: @config.admin_id.to_s,
+            body: content.to_s
+          }
+        end
+
+        payload[:attachment_urls] = options[:attachment_urls] if options[:attachment_urls]
+        payload
+      end
+
+      private
+
+      # 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
+        )
+      end
+    end
+  end
+end

data/lib/flow_chat/intercom/configuration.rb

@@ -0,0 +1,102 @@
+module FlowChat
+  module Intercom
+    class Configuration
+      include FlowChat::NamedConfiguration
+
+      attr_accessor :access_token, :client_secret, :admin_id, :name, :skip_signature_validation
+
+      def initialize(name)
+        @name = name
+        @access_token = nil
+        @client_secret = nil
+        @admin_id = nil
+        @skip_signature_validation = false
+
+        FlowChat.logger.debug { "Intercom::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 { "Intercom::Configuration: Loading configuration from credentials/environment" }
+
+        config = new(nil)
+
+        if defined?(Rails) && Rails.application.credentials.intercom
+          FlowChat.logger.debug { "Intercom::Configuration: Loading from Rails credentials" }
+          credentials = Rails.application.credentials.intercom
+          config.access_token = credentials[:access_token]
+          config.client_secret = credentials[:client_secret]
+          config.admin_id = credentials[:admin_id]
+          config.skip_signature_validation = credentials[:skip_signature_validation] || false
+        else
+          FlowChat.logger.debug { "Intercom::Configuration: Loading from environment variables" }
+          # Fallback to environment variables
+          config.access_token = ENV["INTERCOM_ACCESS_TOKEN"]
+          config.client_secret = ENV["INTERCOM_CLIENT_SECRET"]
+          config.admin_id = ENV["INTERCOM_ADMIN_ID"]
+          config.skip_signature_validation = ENV["INTERCOM_SKIP_SIGNATURE_VALIDATION"] == "true"
+        end
+
+        if config.valid?
+          FlowChat.logger.info { "Intercom::Configuration: Configuration loaded successfully" }
+        else
+          FlowChat.logger.warn { "Intercom::Configuration: Incomplete configuration loaded - missing required fields" }
+        end
+
+        config
+      end
+
+      def valid?
+        is_valid = !!(access_token && !access_token.to_s.empty? && admin_id && !admin_id.to_s.empty?)
+
+        FlowChat.logger.debug { "Intercom::Configuration: Configuration valid: #{is_valid}" }
+        is_valid
+      end
+
+      # API endpoints
+      def api_base_url
+        "https://api.intercom.io"
+      end
+
+      def conversations_url(conversation_id = nil)
+        if conversation_id
+          "#{api_base_url}/conversations/#{conversation_id}"
+        else
+          "#{api_base_url}/conversations"
+        end
+      end
+
+      def conversation_reply_url(conversation_id)
+        "#{conversations_url(conversation_id)}/reply"
+      end
+
+      def conversation_parts_url(conversation_id)
+        "#{conversations_url(conversation_id)}/parts"
+      end
+
+      def conversation_tags_url(conversation_id, tag_id = nil)
+        if tag_id
+          "#{conversations_url(conversation_id)}/tags/#{tag_id}"
+        else
+          "#{conversations_url(conversation_id)}/tags"
+        end
+      end
+
+      def admins_url
+        "#{api_base_url}/admins"
+      end
+
+      # Headers for API requests
+      def api_headers
+        {
+          "Authorization" => "Bearer #{access_token}",
+          "Content-Type" => "application/json",
+          "Accept" => "application/json",
+          "Intercom-Version" => "2.11"
+        }
+      end
+    end
+  end
+end

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