flow_chat 0.9.0 → 0.10.0

data/examples/whatsapp_controller.rb

@@ -11,7 +11,7 @@ class WhatsappController < ApplicationController
       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
@@ -30,7 +30,7 @@ class CustomWhatsappController < ApplicationController
       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/lib/flow_chat/app.rb

@@ -4,7 +4,7 @@ module FlowChat
 
     def initialize(context)
       @context = context
-      @input = context.input
+      @input = build_input
       @navigation_stack = []
     end
 
@@ -13,21 +13,57 @@ module FlowChat
       raise ArgumentError, "screen has already been presented" if navigation_stack.include?(key)
 
       navigation_stack << key
-      return session.get(key) if session.get(key).present?
+      # 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
-      @input = nil # input is being submitted to prompt so we clear it
+      # 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?
 
-      @context.input = nil
+      # 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)
 
@@ -63,16 +99,38 @@ module FlowChat
       context["request.timestamp"]
     end
 
+    # The sender's display name — distinct from a contact card they may share
+    # (that's #contact).
     def contact_name
-      nil
+      context["request.user_name"]
     end
 
-    def location
-      nil
+    # 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
-      nil
+      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
@@ -81,13 +139,73 @@ module FlowChat
 
     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 platform != :ussd && session.get(FlowChat::Input::START).nil?
-        session.set(FlowChat::Input::START, user_input)
-        user_input = nil
+      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/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