flow_chat 0.8.2 → 0.10.0

data/examples/whatsapp_controller.rb

@@ -6,12 +6,12 @@ class WhatsappController < ApplicationController
   skip_forgery_protection
 
   def webhook
-    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: Rails.env.development?) do |config|
+    processor = FlowChat::Processor.new(self, enable_simulator: Rails.env.development?) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
 
-    processor.run WelcomeFlow, :main_page
+    processor.run WhatsappWelcomeFlow, :main_page
   rescue => e
     Rails.logger.error "Error processing WhatsApp webhook: #{e.message}"
     head :internal_server_error
@@ -25,12 +25,12 @@ class CustomWhatsappController < ApplicationController
   def webhook
     custom_config = build_whatsapp_config
 
-    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: !Rails.env.production?) do |config|
+    processor = FlowChat::Processor.new(self, enable_simulator: !Rails.env.production?) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, custom_config
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
 
-    processor.run WelcomeFlow, :main_page
+    processor.run WhatsappWelcomeFlow, :main_page
   rescue => e
     Rails.logger.error "Error processing WhatsApp webhook: #{e.message}"
     head :internal_server_error
@@ -39,7 +39,8 @@ class CustomWhatsappController < ApplicationController
   private
 
   def build_whatsapp_config
-    config = FlowChat::Whatsapp::Configuration.new
+    # Configuration#initialize requires a name; pass nil for an anonymous one.
+    config = FlowChat::Whatsapp::Configuration.new(nil)
 
     case Rails.env
     when "development", "test"
@@ -66,7 +67,7 @@ class CustomWhatsappController < ApplicationController
 end
 
 # Example flow for WhatsApp
-class WelcomeFlow < FlowChat::Flow
+class WhatsappWelcomeFlow < FlowChat::Flow
   def main_page
     name = app.screen(:name) do |prompt|
       prompt.ask "Hello! What's your name?",
@@ -75,9 +76,9 @@ class WelcomeFlow < FlowChat::Flow
 
     choice = app.screen(:main_menu) do |prompt|
       prompt.select "Hi #{name}! How can I help?", {
-        "info" => "📋 Get Information",
-        "support" => "🆘 Contact Support",
-        "feedback" => "💬 Give Feedback"
+        "info" => "Get Information",
+        "support" => "Contact Support",
+        "feedback" => "Give Feedback"
       }
     end
 
@@ -94,36 +95,36 @@ class WelcomeFlow < FlowChat::Flow
   private
 
   def show_info
-    app.say "📍 Located at 123 Main Street\n🕒 Hours: Mon-Fri 9AM-6PM\n📞 Call: (555) 123-4567"
+    app.say "Located at 123 Main Street\nHours: Mon-Fri 9AM-6PM\nCall: (555) 123-4567"
   end
 
   def contact_support
     method = app.screen(:contact_method) do |prompt|
       prompt.select "How would you like to contact us?", {
-        "call" => "📞 Call Us",
-        "email" => "📧 Email Us"
+        "call" => "Call Us",
+        "email" => "Email Us"
       }
     end
 
     case method
     when "call"
-      app.say "📞 Call us at (555) 123-4567"
+      app.say "Call us at (555) 123-4567"
     when "email"
-      app.say "📧 Email us at support@example.com"
+      app.say "Email us at support@example.com"
     end
   end
 
   def collect_feedback
     rating = app.screen(:rating) do |prompt|
-      prompt.select "Rate our service:", ["⭐", "⭐⭐", "⭐⭐⭐", "⭐⭐⭐⭐", "⭐⭐⭐⭐⭐"]
+      prompt.select "Rate our service (1-5):", ["1", "2", "3", "4", "5"]
     end
 
     feedback = app.screen(:feedback_text) do |prompt|
       prompt.ask "Any additional comments?"
     end
 
-    save_feedback(app.phone_number, rating, feedback)
-    app.say "Thank you for your feedback! 🙏"
+    save_feedback(app.msisdn, rating, feedback)
+    app.say "Thank you for your feedback!"
   end
 
   def save_feedback(phone, rating, feedback)

data/examples/whatsapp_media_examples.rb

@@ -1,66 +1,64 @@
 # WhatsApp Media Examples
-# This file demonstrates media usage with FlowChat's WhatsApp integration
+# Demonstrates sending and receiving media with FlowChat's WhatsApp integration.
 
-# Basic media sending with WhatsApp Client
+# Sending media directly with the WhatsApp client, out of band.
 config = FlowChat::Whatsapp::Configuration.from_credentials
 client = FlowChat::Whatsapp::Client.new(config)
 
-# Send different media types
 client.send_image("+1234567890", "https://example.com/image.jpg", "Caption")
 client.send_document("+1234567890", "https://example.com/doc.pdf", "Document title", "filename.pdf")
 client.send_audio("+1234567890", "https://example.com/audio.mp3")
 client.send_video("+1234567890", "https://example.com/video.mp4", "Video caption")
 client.send_sticker("+1234567890", "https://example.com/sticker.webp")
 
-# Using media in flows
+# Sending and receiving media inside a flow.
 class MediaFlow < FlowChat::Flow
   def main_page
-    # Handle incoming media
-    if app.media
+    # app.media is always an Array<FlowChat::Media> (empty when the turn carried
+    # no attachment), so branch on whether it has any items.
+    if app.media.any?
       handle_user_media
       return
     end
 
-    # Send media with prompts
+    # Attach media to a prompt.
     app.screen(:feedback) do |prompt|
       prompt.ask "What do you think?",
-        media: {
-          type: :image,
-          url: "https://example.com/product.jpg"
-        }
+        media: {type: :image, url: "https://example.com/product.jpg"}
     end
 
-    # Send media responses
+    # Attach media to a terminal message.
     app.say "Thanks for your feedback!",
-      media: {
-        type: :video,
-        url: "https://example.com/response.mp4"
-      }
+      media: {type: :video, url: "https://example.com/response.mp4"}
   end
 
   private
 
   def handle_user_media
-    media_type = app.media["type"]
+    # Each item is a FlowChat::Media; item.type is a normalized Symbol
+    # (:image, :video, :audio, :document, :sticker).
+    media = app.media.first
 
-    case media_type
-    when "image"
+    case media.type
+    when :image
       app.say "Thanks for the image! Processing..."
-    when "document"
+    when :document
       app.say "Document received. Reviewing..."
-    when "audio"
+    when :audio
       app.say "Got your voice message!"
-    when "video"
+    when :video
       app.say "Video received. Analyzing..."
+    else
+      app.say "Attachment received."
     end
   end
 end
 
-# Media service for out-of-band messaging
+# An out-of-band service for sending media outside a conversation, for example
+# from a background job or another controller.
 class MediaService
   def initialize
-    @config = FlowChat::Whatsapp::Configuration.from_credentials
-    @client = FlowChat::Whatsapp::Client.new(@config)
+    @client = FlowChat::Whatsapp::Client.new(FlowChat::Whatsapp::Configuration.from_credentials)
   end
 
   def send_welcome_package(phone_number, user_name)
@@ -69,68 +67,18 @@ class MediaService
   end
 
   def send_order_confirmation(phone_number, order_id, invoice_url)
-    @client.send_document(phone_number, invoice_url, "Order ##{order_id} confirmed!", "invoice.pdf")
-    @client.send_buttons(phone_number, "Order confirmed! 🛍️", [
+    @client.send_document(phone_number, invoice_url, "Order ##{order_id} confirmed", "invoice.pdf")
+    @client.send_buttons(phone_number, "Order confirmed", [
       {id: "track", title: "Track Order"},
       {id: "support", title: "Contact Support"}
     ])
   end
-
-  def process_user_media(media_id, media_type, user_phone)
-    # Download and process media
-    @client.get_media_url(media_id)
-    media_content = @client.download_media(media_id)
-
-    # Process based on type
-    case media_type
-    when "image"
-      process_image(media_content, user_phone)
-    when "document"
-      process_document(media_content, user_phone)
-    when "audio"
-      process_audio(media_content, user_phone)
-    end
-  end
-
-  private
-
-  def process_image(content, phone)
-    # Your image processing logic
-    @client.send_text(phone, "Image processed successfully! ✅")
-  end
-
-  def process_document(content, phone)
-    # Your document processing logic
-    @client.send_text(phone, "Document processed! 📄")
-  end
-
-  def process_audio(content, phone)
-    # Your audio processing logic
-    @client.send_text(phone, "Audio processed! 🎵")
-  end
 end
 
-# Controller example for media notifications
+# Controller that sends media notifications on demand.
 class NotificationController < ApplicationController
   def send_media_notification
-    service = MediaService.new
-    service.send_welcome_package(params[:phone], params[:name])
-    render json: {status: "sent"}
-  end
-
-  def send_order_confirmation
-    service = MediaService.new
-    service.send_order_confirmation(
-      params[:phone],
-      params[:order_id],
-      generate_invoice_url(params[:order_id])
-    )
+    MediaService.new.send_welcome_package(params[:phone], params[:name])
     render json: {status: "sent"}
   end
-
-  private
-
-  def generate_invoice_url(order_id)
-    "https://storage.example.com/invoices/#{order_id}.pdf"
-  end
 end

data/flow_chat.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
@@ -36,4 +37,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "actionpack", ">= 6"
   spec.add_dependency "phonelib"
   spec.add_dependency "ibsciss-middleware", "~> 0.4.2"
+  spec.add_dependency "intercom", "~> 4.2"
+  spec.add_dependency "reverse_markdown", "~> 3.0"
+  spec.add_dependency "kramdown", "~> 2.4"
 end

data/lib/flow_chat/app.rb

@@ -0,0 +1,211 @@
+module FlowChat
+  class App
+    attr_reader :input, :context, :navigation_stack
+
+    def initialize(context)
+      @context = context
+      @input = build_input
+      @navigation_stack = []
+    end
+
+    def screen(key)
+      raise ArgumentError, "a block is expected" unless block_given?
+      raise ArgumentError, "screen has already been presented" if navigation_stack.include?(key)
+
+      navigation_stack << key
+      # A screen is answered once its key is stored — even when the stored value is
+      # blank (a caption-less attachment yields ""). Guard on presence-in-session
+      # (non-nil), not truthiness, so media-only (and false/blank) answers stick
+      # instead of re-asking every turn.
+      cached = session.get(key)
+      return cached unless cached.nil?
+
+      user_input = prepare_user_input
+      prompt = FlowChat::Prompt.new user_input
+      # The turn has been handed to a screen; later screens in this run must not
+      # re-consume it. We mark it consumed rather than discarding it, so the
+      # read accessors (text/media/...) stay available for the rest of the run.
+      @input_consumed = true
+
+      value = yield prompt
+      session.set(key, value)
+      value
+    end
+
+    # Consume this turn's message, so no screen answers it later.
+    #
+    # A flow that reads the inbound outside the screen system says so with this.
+    # Routing on the opening message is the usual reason: the flow consumes the
+    # message itself, and FlowChat cannot see that read, so #screen would hand
+    # the same message to the first prompt the run reaches. That prompt is then
+    # answered without ever being asked, and its message never goes out.
+    #
+    # Records the first-message marker that #screen would have written, so the
+    # gate it guards does not fire a turn late and swallow the customer's reply
+    # as though it were the opener.
+    #
+    # Returns the turn, so the caller can read its text and any attachment. The
+    # context keeps both: what is given up is only this turn's right to answer a
+    # screen, not the message itself. Contrast #clear_turn!, which discards the
+    # turn outright because a restart has to rebuild the App without it.
+    def consume_turn!
+      taken = input
+      maybe_note_first_message!(taken)
+      @input_consumed = true
+      taken
+    end
+
+    def go_back
+      return false if navigation_stack.empty?
+
+      # go_back raises RestartFlow, which the executor handles by rebuilding a
+      # fresh App from this same context. A per-instance @input_consumed flag
+      # would be lost on that rebuild, so clear the turn on the shared context
+      # too — otherwise the restarted screen re-consumes the back-trigger
+      # input/attachment as its answer instead of re-prompting.
+      clear_turn!
+      current_screen = navigation_stack.last
+      session.delete(current_screen)
+
+      # Restart the flow from the beginning
+      raise FlowChat::Interrupt::RestartFlow.new
+    end
+
+    def say(msg, media: nil)
+      raise FlowChat::Interrupt::Terminate.new(msg, media: media)
+    end
+
+    def platform
+      context["request.platform"]
+    end
+
+    def gateway
+      context["request.gateway"]
+    end
+
+    def user_id
+      context["request.user_id"]
+    end
+
+    def msisdn
+      context["request.msisdn"]
+    end
+
+    def message_id
+      context["request.message_id"]
+    end
+
+    def timestamp
+      context["request.timestamp"]
+    end
+
+    # The sender's display name — distinct from a contact card they may share
+    # (that's #contact).
+    def contact_name
+      context["request.user_name"]
+    end
+
+    # Read accessors for the turn delegate to the Input value object, which is
+    # the single source of truth for this turn's text and attachments.
+    def text
+      input.text
+    end
+
+    # Always an Array<FlowChat::Media> (empty when none) — a list even on
+    # single-media platforms, so callers iterate uniformly.
+    def media
+      input.media
+    end
+
+    def location
+      input.location
+    end
+
+    def contact
+      input.contact
+    end
+
+    def attachment
+      input.attachment
+    end
+
+    def attachment_type
+      input.attachment_type
+    end
+
+    def session
+      @context.session
+    end
+
+    protected
+
+    # Discard the current turn so a rebuilt App (after RestartFlow) sees an empty
+    # inbound message instead of re-consuming it. Clears both this instance and
+    # the shared context, since the restart builds a new instance from context.
+    def clear_turn!
+      @input_consumed = true
+      @input = FlowChat::Input.new
+      context.input = nil
+      context["request.media"] = nil
+      context["request.location"] = nil
+      context["request.contact"] = nil
+    end
+
+    # The turn as a FlowChat::Input value object. Its #present? accounts for
+    # attachments, so a caption-less photo still answers a screen even though its
+    # text is blank. Built once and kept for the whole run (see #screen).
+    def build_input
+      FlowChat::Input.new(
+        text: context.input,
+        media: wrap_media(context["request.media"]),
+        location: context["request.location"],
+        contact: context["request.contact"]
+      )
+    end
+
+    def wrap_media(raw)
+      return [] unless raw
+
+      items = raw.is_a?(Array) ? raw : [raw]
+      items.map { |data| FlowChat::Media.new(data, platform: platform, client: media_client) }
+    end
+
+    def prepare_user_input
+      return nil if @input_consumed
+
+      user_input = input
+      if maybe_note_first_message!(user_input)
+        # Swallow a text-only opener: the classic "wake the flow / show the first
+        # screen" behavior. An opener that carries an attachment is let through so
+        # the first screen can consume it rather than silently dropping the
+        # media/location/contact.
+        return nil unless user_input.attachment?
+      end
+      user_input
+    end
+
+    # Records this session's opening message if it has not been recorded yet, and
+    # returns whether this turn was it. Whoever meets the turn first records it, a
+    # screen or a flow consuming it itself, so the marker does not depend on which
+    # of them got there. Stores the text, a serializable string, not the Input.
+    #
+    # USSD has no use for the marker: its gateway replays the whole session on
+    # every request, so there is no opener to distinguish.
+    def maybe_note_first_message!(turn)
+      return false if platform == :ussd
+      return false unless session.get(FlowChat::Input::START).nil?
+
+      session.set(FlowChat::Input::START, turn.to_s)
+      true
+    end
+
+    # Every gateway parks its client on the context under its own platform name,
+    # so the lookup is the platform rather than a case per platform. Media on
+    # Messenger and Instagram arrives as a direct CDN url and needs no client to
+    # fetch, but a nil client would still deny a Media object anything the client
+    # is the only route to.
+    def media_client
+      context["#{platform}.client"]
+    end
+  end
+end

data/lib/flow_chat/async_job.rb

@@ -0,0 +1,176 @@
+begin
+  require "active_job"
+rescue LoadError
+  # ActiveJob not available - async features will not be available
+end
+require "ostruct"
+
+module FlowChat
+  # Base class for background flow processing jobs
+  # Users inherit from this and implement execute(controller, **job_params)
+  if defined?(ActiveJob::Base)
+    class AsyncJob < ActiveJob::Base
+      queue_as :default
+
+      def perform(request_context:, **job_params)
+        FlowChat.logger.debug { "AsyncJob: Starting background job with params: #{job_params.inspect}" }
+
+        # Create BackgroundController from serialized request
+        controller = BackgroundController.new(request_context)
+
+        # User implements execute and calls processor.run themselves
+        # Pass job_params as keyword arguments to execute
+        execute(controller, **job_params)
+
+        FlowChat.logger.debug { "AsyncJob: Background job completed successfully" }
+      end
+
+      # Abstract method - user must implement
+      # User builds processor AND calls processor.run themselves
+      # Job params from use_async(JobClass, key: value) are passed as keyword arguments
+      def execute(controller, **job_params)
+        raise NotImplementedError, "Subclasses must implement #execute(controller, **job_params)"
+      end
+    end
+  else
+    # Fallback when ActiveJob is not available
+    class AsyncJob
+      def perform(request_context:, **job_params)
+        FlowChat.logger.debug { "AsyncJob: Starting background job with params: #{job_params.inspect}" }
+
+        # Create BackgroundController from serialized request
+        controller = BackgroundController.new(request_context)
+
+        # User implements execute and calls processor.run themselves
+        # Pass job_params as keyword arguments to execute
+        execute(controller, **job_params)
+
+        FlowChat.logger.debug { "AsyncJob: Background job completed successfully" }
+      end
+
+      # Abstract method - user must implement
+      # User builds processor AND calls processor.run themselves
+      # Job params from use_async(JobClass, key: value) are passed as keyword arguments
+      def execute(controller, **job_params)
+        raise NotImplementedError, "Subclasses must implement #execute(controller, **job_params)"
+      end
+
+      # Stub perform_later for testing when ActiveJob is not available
+      def self.perform_later(args)
+        new.perform(**args)
+      end
+    end
+  end
+
+  # Duck-type controller for background jobs
+  # Provides render/head no-ops and request interface
+  class BackgroundController
+    attr_reader :request, :response
+
+    def initialize(request_data)
+      FlowChat.logger.debug { "BackgroundController: Initializing with request data" }
+      @request = BackgroundRequest.new(request_data)
+      @response = nil
+    end
+
+    # Delegate params to request (mimics Rails controller behavior)
+    def params
+      request.params
+    end
+
+    def render(options)
+      FlowChat.logger.debug { "BackgroundController: render called (no-op): #{options.inspect}" }
+      @response = options
+      nil  # No-op in background
+    end
+
+    def head(status)
+      FlowChat.logger.debug { "BackgroundController: head called (no-op): #{status}" }
+      @response = {status: status}
+      nil  # No-op in background
+    end
+
+    def is_a?(klass)
+      return true if klass == FlowChat::BackgroundController
+      super
+    end
+
+    def kind_of?(klass)
+      return true if klass == FlowChat::BackgroundController
+      super
+    end
+  end
+
+  # Request object for background jobs
+  # Reconstructed from serialized webhook request data
+  class BackgroundRequest
+    attr_reader :params, :method, :headers, :host, :path, :remote_ip
+
+    def initialize(request_data)
+      @params = (request_data[:params] || {}).with_indifferent_access
+      @method = request_data[:method] || "POST"
+      @headers = OpenStruct.new(request_data[:headers] || {})
+      @host = request_data[:host]
+      @path = request_data[:path]
+      @body_content = request_data[:body]
+      @remote_ip = request_data[:remote_ip]
+
+      FlowChat.logger.debug { "BackgroundRequest: Initialized with method=#{@method}, params keys=#{@params.keys.inspect}" }
+    end
+
+    # Rails request interface compatibility
+    def request_method
+      method.upcase
+    end
+
+    def user_agent
+      @headers["User-Agent"]
+    end
+
+    def ssl?
+      # Background jobs don't have SSL context
+      false
+    end
+
+    def post?
+      method.upcase == "POST"
+    end
+
+    def get?
+      method.upcase == "GET"
+    end
+
+    def head?
+      method.upcase == "HEAD"
+    end
+
+    def body
+      # Return StringIO-like object if body content exists
+      @body_content ? BackgroundRequestBody.new(@body_content) : nil
+    end
+
+    def cookies
+      # Background jobs don't have cookies
+      {}
+    end
+  end
+
+  # Body wrapper for BackgroundRequest
+  # Provides read() method that Rails expects
+  class BackgroundRequestBody
+    def initialize(content)
+      @content = content
+      @read = false
+    end
+
+    def read
+      return "" if @read
+      @read = true
+      @content
+    end
+
+    def rewind
+      @read = false
+    end
+  end
+end