flow_chat 0.8.2 → 0.10.0

data/lib/flow_chat/choice_titles.rb

@@ -0,0 +1,95 @@
+module FlowChat
+  # Decides, once per choice set rather than once per choice, whether every
+  # title in that set needs a 1-based position prefix ("1. ", "2. ", and so
+  # on), then returns the on-screen title FlowChat will render for each
+  # choice.
+  #
+  # The trigger is ambiguity, not truncation specifically: a screen is
+  # ambiguous when, having computed each choice's title at the rung's cap,
+  # either any title had to be truncated, or two choices land on the same
+  # title. Both mean the titles as displayed cannot identify a choice on
+  # their own:
+  #
+  # - Truncation can make two different labels ("Transfer to savings
+  #   account" / "Transfer to salary account") land on the same displayed
+  #   text ("Transfer to sa...").
+  # - Two choices can share a label outright with no truncation involved at
+  #   all (two accounts both nicknamed "Savings", a menu with two literal
+  #   "Accept" options) - the keys behind them differ, but the titles a user
+  #   would type back are identical.
+  #
+  # Numbering is decided for the whole set, never per choice: prefixing only
+  # the affected title would produce "Yes" / "2. Transfer to savi...", a
+  # stray number with no "1." next to it to make sense of.
+  #
+  # The renderer and every choice mapper share this one decision, for the
+  # same reason FlowChat::TextTruncator is shared: two independent
+  # reimplementations could disagree about which rung is ambiguous, and a
+  # disagreement here means a title on screen that nothing resolves.
+  module ChoiceTitles
+    IDENTITY = ->(string) { string }
+
+    # @param choices [Hash] original choice key => label, in the order the
+    #   caller numbers positions in - the renderer and the mapper must
+    #   enumerate the same choices in the same order, or the titles and
+    #   aliases they compute will not match
+    # @param cap [Integer] the rung's title length limit
+    # @return [Array<[String, String, String, Boolean]>] one
+    #   [key, original_label, displayed_title, label_was_truncated] tuple per
+    #   choice, in the same order as `choices`
+    # @param fold [Proc] the normalization the resolver applies to input
+    #   before matching it. Two titles that fold to the same string cannot
+    #   be told apart by that resolver, so the set is ambiguous and gets
+    #   numbered. USSD is the one mapper that needs no fold: it resolves on
+    #   position, which is injective by construction.
+    # @param measure [Symbol] :characters or :bytes, whichever unit the
+    #   platform sizes the field in
+    def self.build(choices, cap, fold: IDENTITY, measure: :characters)
+      reason = ambiguity_reason(choices, cap, fold: fold, measure: measure)
+      prefixed = !reason.nil?
+
+      if prefixed
+        FlowChat.logger.debug { "#{name}: numbering choices, titles are ambiguous (#{reason})" }
+      end
+
+      choices.map.with_index(1) do |(key, label), position|
+        label = label.to_s
+        width = (measure == :bytes) ? label.bytesize : label.length
+
+        if prefixed
+          prefix = "#{position}. "
+          prefix_width = (measure == :bytes) ? prefix.bytesize : prefix.length
+          title = FlowChat::TextTruncator.number(label, position, cap, measure: measure)
+          truncated = width > (cap - prefix_width)
+        else
+          title = FlowChat::TextTruncator.truncate(label, cap, measure: measure)
+          truncated = width > cap
+        end
+
+        [key.to_s, label, title, truncated]
+      end
+    end
+
+    # @return [Boolean] whether this choice set is ambiguous at this cap
+    def self.ambiguous?(choices, cap, fold: IDENTITY, measure: :characters)
+      !ambiguity_reason(choices, cap, fold: fold, measure: measure).nil?
+    end
+
+    # @return [String, nil] a description of why the set is ambiguous, for
+    #   logging, or nil when it is not
+    def self.ambiguity_reason(choices, cap, fold: IDENTITY, measure: :characters)
+      labels = choices.map { |_, label| label.to_s }
+      titles = labels.map { |label| FlowChat::TextTruncator.truncate(label, cap, measure: measure) }
+
+      truncated_labels = labels.zip(titles).select { |label, title| title != label }.map(&:first)
+      duplicate_titles = titles.map { |title| fold.call(title) }.tally.select { |_, count| count > 1 }.keys
+
+      return nil if truncated_labels.empty? && duplicate_titles.empty?
+
+      parts = []
+      parts << "truncated: #{truncated_labels.inspect}" unless truncated_labels.empty?
+      parts << "duplicate titles: #{duplicate_titles.inspect}" unless duplicate_titles.empty?
+      parts.join(", ")
+    end
+  end
+end

data/lib/flow_chat/config.rb

@@ -7,6 +7,39 @@ module FlowChat
     # When true (default), validation errors are combined with the original message.
     # When false, only the validation error message is shown to the user.
     mattr_accessor :combine_validation_error_with_message, default: true
+    # When true, inject logger into middleware stack. Defaults to true in Rails development.
+    mattr_accessor :inject_middleware_logger, default: defined?(Rails) && Rails.env.development?
+
+    # Called with the turn's context and the error when a gateway cannot
+    # deliver a reply the flow produced, before the error is re-raised.
+    #
+    # For the app that owns the turn, acting on records only it knows about: a
+    # gateway sends after the middleware stack has returned, so an app that
+    # recorded the reply has already recorded it as sent, and nothing
+    # downstream of the send can tell it otherwise.
+    #
+    # The whole context, because this is the app's own code reading what the
+    # app put there. Anything wanting only to watch deliveries fail should
+    # subscribe to message.delivery_failed instead, which carries no more than
+    # a successful send announces.
+    #
+    # Raising here would replace the delivery error with this one, so an
+    # exception is logged and dropped.
+    mattr_accessor :on_delivery_failure, default: nil
+
+    # Called with (context, result) once a reply has actually been delivered,
+    # where result is whatever the platform's client returned. The mirror of
+    # on_delivery_failure, and the only place an app can learn the id the platform
+    # gave a message: gateways deliver after the middleware stack has unwound, so
+    # a row written during the turn does not yet know it.
+    #
+    # Every gateway that delivers out of band names that id the same way, on the
+    # context as "delivery.platform_message_id", so an app does not have to know
+    # the shape of each platform's answer.
+    #
+    # Raising here would replace a successful send with an error, so an exception
+    # is logged and dropped.
+    mattr_accessor :on_delivery_success, default: nil
 
     # Session configuration object
     def self.session
@@ -28,8 +61,18 @@ module FlowChat
       @http ||= HttpConfig.new
     end
 
+    # Messenger-specific configuration object
+    def self.messenger
+      @messenger ||= MessengerConfig.new
+    end
+
+    # Instagram-specific configuration object
+    def self.instagram
+      @instagram ||= InstagramConfig.new
+    end
+
     class SessionConfig
-      attr_accessor :boundaries, :hash_identifiers, :identifier
+      attr_accessor :boundaries, :hash_identifiers, :identifier, :session_id_proc
 
       def initialize
         # Session boundaries control how session IDs are constructed
@@ -37,14 +80,17 @@ module FlowChat
         # :gateway = separate sessions per gateway
         # :platform = separate sessions per platform (ussd, whatsapp)
         @boundaries = [:flow, :gateway, :platform]
-        
+
         # Always hash phone numbers for privacy
         @hash_identifiers = true
-        
+
         # Session identifier type (nil = let platforms choose their default)
         # :msisdn = durable sessions (durable across timeouts)
         # :request_id = ephemeral sessions (new session each time)
         @identifier = nil
+
+        # Proc for custom session ID generation (overrides default behavior when set)
+        @session_id_proc = nil
       end
     end
 
@@ -62,35 +108,92 @@ module FlowChat
     end
 
     class WhatsappConfig
-      attr_accessor :background_job_class
-      attr_reader :message_handling_mode, :api_base_url
+      # api_base_url is writable, unlike the limits beside it. Those are facts
+      # about the platform that an application cannot change by disagreeing. The
+      # version in the host is a choice, and one an application has to be able
+      # to make: Meta retires a version roughly every two years and pins the
+      # webhook payloads it sends to whatever the app's dashboard says, so an
+      # application straddling two versions must be able to close the gap
+      # without waiting for a release here.
+      attr_accessor :api_base_url
+      attr_reader :max_buttons, :max_list_rows
 
       def initialize
-        @message_handling_mode = :inline
-        @background_job_class = "WhatsappMessageJob"
-        @api_base_url = "https://graph.facebook.com/v22.0"
+        @api_base_url = "https://graph.facebook.com/v23.0"
+        # Meta: "You cannot have more than 3 buttons in an interactive message."
+        @max_buttons = 3
+        # Meta: "up to 10 sections, with up to 10 rows for all sections combined".
+        @max_list_rows = 10
       end
 
-      # Validate message handling mode
-      def message_handling_mode=(mode)
-        valid_modes = [:inline, :background, :simulator]
-        unless valid_modes.include?(mode.to_sym)
-          raise ArgumentError, "Invalid message handling mode: #{mode}. Valid modes: #{valid_modes.join(", ")}"
-        end
-        @message_handling_mode = mode.to_sym
+      # Bridges max_buttons/max_list_rows to the shape
+      # FlowChat::Meta::ChoiceLadder expects, so the renderer and the choice
+      # mapper can both ask it which rung a count lands on instead of each
+      # re-deriving the same two-threshold comparison independently.
+      #
+      # WhatsApp's list has no further structure the way Messenger's
+      # carousel has elements and buttons per element - it is just a flat
+      # row cap - so it is modelled as a single element holding every row
+      # (max_buttons_per_element: 1) purely to fit ChoiceLadder's
+      # carousel_capacity formula (elements * buttons_per_element). That
+      # shape stays private to this adapter rather than becoming
+      # max_buttons/max_list_rows' own public meaning, since "carousel" and
+      # "buttons per element" describe nothing WhatsApp actually has.
+      def ladder_limits
+        LADDER_LIMITS_SHAPE.new(max_buttons, max_list_rows, 1)
       end
 
-      # Helper methods for mode checking
-      def inline_mode?
-        @message_handling_mode == :inline
-      end
+      LADDER_LIMITS_SHAPE = Struct.new(:max_quick_replies, :max_carousel_elements, :max_buttons_per_element)
+    end
 
-      def background_mode?
-        @message_handling_mode == :background
+    class MessengerConfig
+      # Writable for the same reason as WhatsappConfig's, above.
+      attr_accessor :api_base_url
+      attr_reader :max_text_length, :max_quick_replies,
+        :max_quick_reply_title, :max_carousel_elements, :max_buttons_per_element,
+        :max_button_title, :max_element_title
+
+      def initialize
+        @api_base_url = "https://graph.facebook.com/v23.0"
+        # Meta does not state a text limit for Messenger on any current reference
+        # page, unlike Instagram's documented 1,000 bytes. 2000 is the long-cited
+        # figure and is safe to be wrong about in this direction: the client
+        # splits text at this value rather than truncating it, so a limit set too
+        # low sends an extra message and one set too high gets rejected. Raise it
+        # only against a documented figure.
+        @max_text_length = 2000
+        @max_quick_replies = 13
+        @max_quick_reply_title = 20
+        @max_carousel_elements = 10
+        @max_buttons_per_element = 3
+        @max_button_title = 20
+        @max_element_title = 80
       end
+    end
+
+    class InstagramConfig
+      # Both hosts writable, and separately: the two integration paths are
+      # configured independently at Meta, so an application moving one to a new
+      # version has not necessarily moved the other.
+      attr_accessor :api_base_url, :instagram_login_api_base_url
+      attr_reader :max_text_length, :max_quick_replies,
+        :max_quick_reply_title, :max_carousel_elements, :max_buttons_per_element,
+        :max_button_title, :max_element_title
 
-      def simulator_mode?
-        @message_handling_mode == :simulator
+      def initialize
+        # Facebook Login path: the linked Page speaks through the general Graph API host.
+        @api_base_url = "https://graph.facebook.com/v23.0"
+        # Instagram Login path: the Instagram professional account speaks through its
+        # own host instead, with no Facebook Page in the picture at all.
+        @instagram_login_api_base_url = "https://graph.instagram.com/v23.0"
+        # Meta: "Message text must be UTF-8 and be 1,000 bytes or less."
+        @max_text_length = 1000
+        @max_quick_replies = 13
+        @max_quick_reply_title = 20
+        @max_carousel_elements = 10
+        @max_buttons_per_element = 3
+        @max_button_title = 20
+        @max_element_title = 80
       end
     end
 

data/lib/flow_chat/delivery_error.rb

@@ -0,0 +1,9 @@
+module FlowChat
+  # A reply the flow produced that the platform would not take.
+  #
+  # Raised by nothing: it exists so that a send which failed quietly, by
+  # answering nil rather than raising, still reaches on_delivery_failure and
+  # MESSAGE_DELIVERY_FAILED carrying something that names what happened. A
+  # subscriber written against a raising client sees the same shape either way.
+  class DeliveryError < StandardError; end
+end

data/lib/flow_chat/{base_executor.rb → executor.rb}

@@ -1,8 +1,8 @@
 module FlowChat
-  class BaseExecutor
+  class Executor
     def initialize(app)
       @app = app
-      FlowChat.logger.debug { "#{log_prefix}: Initialized #{platform_name} executor middleware" }
+      FlowChat.logger.debug { "#{log_prefix}: Initialized executor middleware" }
     end
 
     def call(context)
@@ -13,7 +13,7 @@ module FlowChat
       FlowChat.logger.info { "#{log_prefix}: Executing flow #{flow_class.name}##{action} for session #{session_id}" }
 
       platform_app = build_platform_app(context)
-      FlowChat.logger.debug { "#{log_prefix}: #{platform_name} app built for flow execution" }
+      FlowChat.logger.debug { "#{log_prefix}: app built for flow execution" }
 
       flow = flow_class.new platform_app
       FlowChat.logger.debug { "#{log_prefix}: Flow instance created, invoking #{action} method" }
@@ -41,17 +41,12 @@ module FlowChat
 
     protected
 
-    # Subclasses must implement these methods
-    def platform_name
-      raise NotImplementedError, "Subclasses must implement platform_name"
-    end
-
     def log_prefix
-      raise NotImplementedError, "Subclasses must implement log_prefix"
+      "Executor"
     end
 
     def build_platform_app(context)
-      raise NotImplementedError, "Subclasses must implement build_platform_app"
+      FlowChat::App.new(context)
     end
   end
-end 
+end

data/lib/flow_chat/factory.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module FlowChat
+  # Factory provides centralized processor configuration for consistent setup across
+  # webhook and background contexts.
+  #
+  # Example:
+  #   # In config/initializers/flow_chat.rb
+  #   FlowChat::Factory.register :whatsapp do |controller|
+  #     processor = FlowChat::Processor.new(controller) do |config|
+  #       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+  #       config.use_session_store FlowChat::Session::CacheSessionStore
+  #       config.use_session_config(boundaries: [:flow])
+  #       config.use_async(WhatsAppFlowJob)
+  #     end
+  #     processor.run(WhatsAppFlow, :start)
+  #   end
+  #
+  #   # In webhook controller
+  #   FlowChat::Factory.execute(:whatsapp, controller: self)
+  #
+  #   # In background job
+  #   FlowChat::Factory.execute(:whatsapp, controller: controller)
+  class Factory
+    class << self
+      # Register a processor factory with a given name
+      #
+      # @param name [Symbol] The factory name (e.g., :whatsapp, :intercom)
+      # @param block [Proc] The factory block that receives controller
+      # @return [void]
+      #
+      # @example
+      #   FlowChat::Factory.register :whatsapp do |controller|
+      #     processor = FlowChat::Processor.new(controller) do |config|
+      #       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      #     end
+      #     processor.run(WhatsAppFlow, :start)
+      #   end
+      def register(name, &block)
+        FlowChat.logger.debug { "Factory: Registering factory '#{name}'" }
+        factories[name] = block
+      end
+
+      # Execute a registered factory
+      #
+      # @param name [Symbol] The factory name
+      # @param controller [Object] The controller instance (webhook or background)
+      # @return [void]
+      # @raise [FactoryNotFoundError] If factory is not registered
+      #
+      # @example
+      #   FlowChat::Factory.execute(:whatsapp, controller: self)
+      def execute(name, controller:)
+        factory = factories[name]
+        raise FactoryNotFoundError, "Factory '#{name}' not registered" unless factory
+
+        FlowChat.logger.debug { "Factory: Executing factory '#{name}'" }
+        factory.call(controller)
+      end
+
+      # Check if a factory is registered
+      #
+      # @param name [Symbol] The factory name
+      # @return [Boolean]
+      def registered?(name)
+        factories.key?(name)
+      end
+
+      # Get all registered factory names
+      #
+      # @return [Array<Symbol>]
+      def registered_factories
+        factories.keys
+      end
+
+      # Clear all registered factories (primarily for testing)
+      #
+      # @return [void]
+      def clear!
+        FlowChat.logger.debug { "Factory: Clearing all registered factories" }
+        factories.clear
+      end
+
+      private
+
+      def factories
+        @factories ||= {}
+      end
+    end
+
+    # Error raised when attempting to execute an unregistered factory
+    class FactoryNotFoundError < StandardError; end
+  end
+end

data/lib/flow_chat/gateway_async_support.rb

@@ -0,0 +1,106 @@
+require_relative "async_job"
+
+module FlowChat
+  # Concern for gateways to support async background processing
+  # Mix this into gateway classes to enable async detection and job enqueueing
+  module GatewayAsyncSupport
+    attr_reader :controller, :context
+
+    # Check if gateway supports async processing
+    # Override in gateways that don't support async (e.g., USSD)
+    def async_supported?
+      true
+    end
+
+    # Detect if we're currently in background mode
+    def in_background?
+      @controller.is_a?(::FlowChat::BackgroundController)
+    end
+
+    # Check if async processing should be used
+    # Returns true if:
+    # - Not already in background mode
+    # - Processor has async enabled
+    # - Gateway supports async
+    def should_enqueue_async?
+      processor = @context["processor"]
+
+      !in_background? &&
+        processor&.async_enabled? &&
+        async_supported?
+    end
+
+    # Enqueue background job with serialized request context
+    # Returns true if job was enqueued, false otherwise
+    def enqueue_async_job
+      return false unless should_enqueue_async?
+
+      processor = @context["processor"]
+
+      FlowChat.logger.info { "#{self.class.name}: Async enabled - enqueuing background job" }
+
+      # Serialize request data for BackgroundController
+      request_data = {
+        params: @controller.request.params.to_h,
+        method: @controller.request.method,
+        headers: extract_headers_for_background(@controller.request),
+        host: extract_host(@controller.request),
+        path: extract_path(@controller.request),
+        body: extract_body_for_background(@controller.request),
+        remote_ip: extract_remote_ip(@controller.request)
+      }
+
+      # Enqueue user's job with request context and job params
+      processor.async_job_class.perform_later(
+        request_context: request_data,
+        **processor.async_job_params
+      )
+
+      FlowChat.logger.info { "#{self.class.name}: Background job enqueued successfully" }
+
+      true
+    end
+
+    # Extract serializable headers needed for background processing
+    # Override in gateways that need additional headers
+    def extract_headers_for_background(request)
+      {
+        "Content-Type" => request.headers["Content-Type"],
+        "User-Agent" => request.headers["User-Agent"]
+      }.compact
+    end
+
+    # Extract host from request for URL boundary support
+    def extract_host(request)
+      request.host
+    rescue
+      nil
+    end
+
+    # Extract path from request for URL boundary support
+    def extract_path(request)
+      request.path
+    rescue
+      nil
+    end
+
+    # Extract request body for background processing
+    # Override in gateways that need the request body
+    def extract_body_for_background(request)
+      return nil unless request.body
+
+      body_content = request.body.read
+      request.body.rewind  # Reset for subsequent reads
+      body_content
+    rescue
+      nil
+    end
+
+    # Extract remote IP from request
+    def extract_remote_ip(request)
+      request.remote_ip
+    rescue
+      nil
+    end
+  end
+end

data/lib/flow_chat/generic_async_job.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module FlowChat
+  # Generic background job that uses the Factory pattern
+  # Automatically used when use_async is called without a job class
+  #
+  # Example:
+  #   # In webhook controller
+  #   processor = FlowChat::Processor.new(self) do |config|
+  #     config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+  #     config.use_session_store FlowChat::Session::CacheSessionStore
+  #     config.use_async(factory: :whatsapp)  # No job class - uses GenericAsyncJob
+  #   end
+  #
+  #   # Background job executes:
+  #   FlowChat::Factory.execute(:whatsapp, controller: controller)
+  class GenericAsyncJob < AsyncJob
+    def execute(controller, factory:, **job_params)
+      FlowChat.logger.debug { "GenericAsyncJob: Executing factory '#{factory}' with params: #{job_params.inspect}" }
+
+      unless FlowChat::Factory.registered?(factory)
+        raise FlowChat::Factory::FactoryNotFoundError, "Factory '#{factory}' not registered"
+      end
+
+      FlowChat::Factory.execute(factory, controller: controller)
+
+      FlowChat.logger.debug { "GenericAsyncJob: Factory '#{factory}' executed successfully" }
+    end
+  end
+end

data/lib/flow_chat/http/configuration_error.rb

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