flow_chat 0.8.2 → 0.10.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flow_chat
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.10.0
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-28 00:00:00.000000000 Z
+date: 2026-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -80,6 +80,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.4.2
+- !ruby/object:Gem::Dependency
+  name: intercom
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: reverse_markdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
 description: "FlowChat is a Rails framework for building sophisticated conversational
   interfaces across USSD and WhatsApp platforms. \nCreate interactive flows with menus,
   prompts, validation, media support, and session management. Features include \nmulti-tenancy,
@@ -92,9 +134,16 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".DS_Store"
+- ".cliff.toml"
 - ".github/workflows/ci.yml"
+- ".github/workflows/pages.yml"
+- ".github/workflows/release.yml"
 - ".gitignore"
 - ".ruby-version"
+- ".standard.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -102,71 +151,129 @@ files:
 - SECURITY.md
 - bin/console
 - bin/setup
+- docs/architecture.md
+- docs/async-background-processing.md
 - docs/configuration.md
-- docs/flows.md
-- docs/http-gateway-protocol.md
-- docs/images/simulator.png
+- docs/factory-pattern.md
+- docs/gateway-context-variables.md
+- docs/gateway-development.md
+- docs/getting-started.md
 - docs/instrumentation.md
-- docs/media.md
-- docs/sessions.md
+- docs/platforms/instagram.md
+- docs/platforms/messenger.md
+- docs/platforms/telegram.md
+- docs/platforms/ussd.md
+- docs/platforms/whatsapp.md
+- docs/superpowers/plans/2026-07-09-inbound-media-support.md
+- docs/superpowers/plans/2026-07-09-inbound-media-support.md.tasks.json
+- docs/superpowers/plans/2026-08-10-messenger-instagram.md
+- docs/superpowers/plans/2026-08-10-messenger-instagram.md.tasks.json
+- docs/superpowers/plans/2026-08-16-unified-choice-resolution.md
+- docs/superpowers/plans/2026-08-16-unified-choice-resolution.md.tasks.json
+- docs/superpowers/specs/2026-07-09-inbound-media-support-design.md
+- docs/superpowers/specs/2026-08-10-messenger-instagram-design.md
 - docs/testing.md
-- docs/ussd-setup.md
-- docs/whatsapp-setup.md
+- examples/custom_session_id_example.rb
 - examples/http_controller.rb
+- examples/intercom_configuration_example.rb
+- examples/intercom_controller.rb
 - examples/multi_tenant_whatsapp_controller.rb
 - examples/simulator_controller.rb
 - examples/ussd_controller.rb
 - examples/whatsapp_controller.rb
 - examples/whatsapp_media_examples.rb
-- examples/whatsapp_message_job.rb
 - flow_chat.gemspec
 - lib/flow_chat.rb
-- lib/flow_chat/base_app.rb
-- lib/flow_chat/base_executor.rb
-- lib/flow_chat/base_processor.rb
+- lib/flow_chat/app.rb
+- lib/flow_chat/async_job.rb
+- lib/flow_chat/choice_titles.rb
 - lib/flow_chat/config.rb
 - lib/flow_chat/context.rb
+- lib/flow_chat/delivery_error.rb
+- lib/flow_chat/executor.rb
+- lib/flow_chat/factory.rb
 - lib/flow_chat/flow.rb
-- lib/flow_chat/http/app.rb
+- lib/flow_chat/gateway_async_support.rb
+- lib/flow_chat/generic_async_job.rb
+- lib/flow_chat/http/configuration_error.rb
 - lib/flow_chat/http/gateway/simple.rb
-- lib/flow_chat/http/middleware/executor.rb
-- lib/flow_chat/http/processor.rb
+- lib/flow_chat/http/middleware/choice_mapper.rb
 - lib/flow_chat/http/renderer.rb
+- lib/flow_chat/input.rb
+- lib/flow_chat/instagram/client.rb
+- lib/flow_chat/instagram/configuration.rb
+- lib/flow_chat/instagram/configuration_error.rb
+- lib/flow_chat/instagram/gateway/send_api.rb
+- lib/flow_chat/instagram/middleware/choice_mapper.rb
+- lib/flow_chat/instagram/renderer.rb
 - lib/flow_chat/instrumentation.rb
 - lib/flow_chat/instrumentation/log_subscriber.rb
 - lib/flow_chat/instrumentation/metrics_collector.rb
 - lib/flow_chat/instrumentation/setup.rb
+- lib/flow_chat/intercom/client.rb
+- lib/flow_chat/intercom/configuration.rb
+- lib/flow_chat/intercom/configuration_error.rb
+- lib/flow_chat/intercom/gateway/intercom_api.rb
+- lib/flow_chat/intercom/middleware/choice_mapper.rb
+- lib/flow_chat/intercom/renderer.rb
 - lib/flow_chat/interrupt.rb
+- lib/flow_chat/media.rb
+- lib/flow_chat/messenger/client.rb
+- lib/flow_chat/messenger/configuration.rb
+- lib/flow_chat/messenger/configuration_error.rb
+- lib/flow_chat/messenger/gateway/send_api.rb
+- lib/flow_chat/messenger/middleware/choice_mapper.rb
+- lib/flow_chat/messenger/renderer.rb
+- lib/flow_chat/meta/challenge.rb
+- lib/flow_chat/meta/choice_ladder.rb
+- lib/flow_chat/meta/configuration_error.rb
+- lib/flow_chat/meta/gateway_identity.rb
+- lib/flow_chat/meta/messaging_gateway.rb
+- lib/flow_chat/meta/signature.rb
+- lib/flow_chat/meta/signature_validation.rb
+- lib/flow_chat/meta/webhook_verification.rb
+- lib/flow_chat/named_configuration.rb
 - lib/flow_chat/phone_number_util.rb
+- lib/flow_chat/processor.rb
 - lib/flow_chat/prompt.rb
+- lib/flow_chat/renderers/markdown_support.rb
+- lib/flow_chat/security.rb
 - lib/flow_chat/session/cache_session_store.rb
 - lib/flow_chat/session/middleware.rb
-- lib/flow_chat/session/rails_session_store.rb
 - lib/flow_chat/simulator/controller.rb
 - lib/flow_chat/simulator/views/simulator.html.erb
-- lib/flow_chat/ussd/app.rb
+- lib/flow_chat/telegram.rb
+- lib/flow_chat/telegram/client.rb
+- lib/flow_chat/telegram/configuration.rb
+- lib/flow_chat/telegram/configuration_error.rb
+- lib/flow_chat/telegram/gateway/bot_api.rb
+- lib/flow_chat/telegram/middleware/choice_mapper.rb
+- lib/flow_chat/telegram/renderer.rb
+- lib/flow_chat/text_truncator.rb
 - lib/flow_chat/ussd/gateway/nalo.rb
-- lib/flow_chat/ussd/gateway/nsano.rb
 - lib/flow_chat/ussd/middleware/choice_mapper.rb
-- lib/flow_chat/ussd/middleware/executor.rb
 - lib/flow_chat/ussd/middleware/pagination.rb
-- lib/flow_chat/ussd/processor.rb
 - lib/flow_chat/ussd/renderer.rb
 - lib/flow_chat/version.rb
-- lib/flow_chat/whatsapp/app.rb
 - lib/flow_chat/whatsapp/client.rb
 - lib/flow_chat/whatsapp/configuration.rb
+- lib/flow_chat/whatsapp/configuration_error.rb
 - lib/flow_chat/whatsapp/gateway/cloud_api.rb
-- lib/flow_chat/whatsapp/middleware/executor.rb
-- lib/flow_chat/whatsapp/processor.rb
+- lib/flow_chat/whatsapp/middleware/choice_mapper.rb
 - lib/flow_chat/whatsapp/renderer.rb
-- lib/flow_chat/whatsapp/send_job_support.rb
 - lib/flow_chat/whatsapp/template_manager.rb
+- lib/tasks/release.rake
+- site/.nojekyll
+- site/.og-card.html
+- site/favicon.svg
+- site/index.html
+- site/og.png
 homepage: https://github.com/radioactive-labs/flow_chat
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/radioactive-labs/flow_chat
   source_code_uri: https://github.com/radioactive-labs/flow_chat
   changelog_uri: https://github.com/radioactive-labs/flow_chat

data/docs/flows.md

@@ -1,320 +0,0 @@
-# Flow Development Guide
-
-This guide covers advanced flow patterns, validation techniques, and best practices for building sophisticated conversational workflows.
-
-## Flow Architecture
-
-### Flow Lifecycle
-
-Every flow method must result in user interaction:
-
-```ruby
-class ExampleFlow < FlowChat::Flow
-  def main_page
-    # ✅ Always end with user interaction
-    choice = app.screen(:choice) { |p| p.select "Choose:", ["A", "B"] }
-    
-    case choice
-    when "A"
-      handle_option_a
-      app.say "Option A completed!"  # Required interaction
-    when "B"  
-      handle_option_b
-      app.say "Option B completed!"  # Required interaction
-    end
-  end
-end
-```
-
-### Session Management
-
-FlowChat automatically persists screen results:
-
-```ruby
-class RegistrationFlow < FlowChat::Flow
-  def main_page
-    # These values persist across requests
-    name = app.screen(:name) { |p| p.ask "Name?" }
-    email = app.screen(:email) { |p| p.ask "Email?" }
-    
-    # Show summary using cached values
-    confirmed = app.screen(:confirm) do |prompt|
-      prompt.yes? "Create account for #{name} (#{email})?"
-    end
-    
-    if confirmed
-      create_user(name: name, email: email)
-      app.say "Account created!"
-    end
-  end
-end
-```
-
-## Input Validation Patterns
-
-### Basic Validation
-
-```ruby
-age = app.screen(:age) do |prompt|
-  prompt.ask "Enter your age:",
-    validate: ->(input) { 
-      return "Age must be a number" unless input.match?(/^\d+$/)
-      return "Must be 18 or older" unless input.to_i >= 18
-      nil  # Return nil for valid input
-    },
-    transform: ->(input) { input.to_i }
-end
-```
-
-### Complex Validation
-
-```ruby
-phone = app.screen(:phone) do |prompt|
-  prompt.ask "Enter phone number:",
-    validate: ->(input) {
-      clean = input.gsub(/[\s\-\(\)]/, '')
-      return "Invalid format" unless clean.match?(/^\+?[\d]{10,15}$/)
-      return "Must start with country code" unless clean.start_with?('+')
-      nil
-    },
-    transform: ->(input) { input.gsub(/[\s\-\(\)]/, '') }
-end
-```
-
-### Conditional Validation
-
-```ruby
-class PaymentFlow < FlowChat::Flow
-  def collect_payment_method
-    method = app.screen(:method) do |prompt|
-      prompt.select "Payment method:", ["card", "mobile_money"]
-    end
-    
-    if method == "card"
-      collect_card_details
-    else
-      collect_mobile_money_details
-    end
-  end
-  
-  private
-  
-  def collect_card_details
-    card = app.screen(:card) do |prompt|
-      prompt.ask "Card number (16 digits):",
-        validate: ->(input) {
-          clean = input.gsub(/\s/, '')
-          return "Must be 16 digits" unless clean.length == 16
-          return "Invalid card number" unless luhn_valid?(clean)
-          nil
-        }
-    end
-    
-    app.say "Card ending in #{card[-4..-1]} saved."
-  end
-end
-```
-
-## Menu Patterns
-
-### Dynamic Menus
-
-```ruby
-def show_products
-  products = fetch_available_products
-  
-  choice = app.screen(:product) do |prompt|
-    prompt.select "Choose product:", products.map(&:name)
-  end
-  
-  selected_product = products.find { |p| p.name == choice }
-  show_product_details(selected_product)
-end
-```
-
-### Nested Menus
-
-```ruby
-def main_menu
-  choice = app.screen(:main) do |prompt|
-    prompt.select "Main Menu:", {
-      "products" => "View Products",
-      "orders" => "My Orders", 
-      "support" => "Customer Support"
-    }
-  end
-  
-  case choice
-  when "products"
-    products_menu
-  when "orders"
-    orders_menu
-  when "support"
-    support_menu
-  end
-end
-```
-
-## Advanced Patterns
-
-### Multi-Step Forms
-
-```ruby
-class CompleteProfileFlow < FlowChat::Flow
-  def main_page
-    collect_basic_info
-    collect_preferences
-    confirm_and_save
-  end
-  
-  private
-  
-  def collect_basic_info
-    app.screen(:name) { |p| p.ask "Full name:" }
-    app.screen(:email) { |p| p.ask "Email:" }
-    app.screen(:phone) { |p| p.ask "Phone:" }
-  end
-  
-  def collect_preferences
-    app.screen(:language) { |p| p.select "Language:", ["English", "French"] }
-    app.screen(:notifications) { |p| p.yes? "Enable notifications?" }
-  end
-  
-  def confirm_and_save
-    summary = build_summary
-    confirmed = app.screen(:confirm) { |p| p.yes? "Save profile?\n\n#{summary}" }
-    
-    if confirmed
-      save_profile
-      app.say "Profile saved successfully!"
-    else
-      app.say "Profile not saved."
-    end
-  end
-end
-```
-
-### Error Recovery
-
-```ruby
-def process_payment
-  begin
-    amount = app.screen(:amount) do |prompt|
-      prompt.ask "Amount to pay:",
-        validate: ->(input) {
-          return "Invalid amount" unless input.match?(/^\d+(\.\d{2})?$/)
-          return "Minimum $1.00" unless input.to_f >= 1.0
-          nil
-        },
-        transform: ->(input) { input.to_f }
-    end
-    
-    process_transaction(amount)
-    app.say "Payment of $#{amount} processed successfully!"
-    
-  rescue PaymentError => e
-    app.say "Payment failed: #{e.message}. Please try again."
-    process_payment  # Retry
-  end
-end
-```
-
-## Cross-Platform Considerations
-
-### Platform Detection
-
-```ruby
-def show_help
-  if app.context["request.gateway"] == :whatsapp_cloud_api
-    # WhatsApp users get rich media
-    app.say "Here's how to use our service:",
-      media: { type: :image, url: "https://example.com/help.jpg" }
-  else
-    # USSD users get text with link
-    app.say "Help guide: https://example.com/help"
-  end
-end
-```
-
-### Progressive Enhancement
-
-```ruby
-def collect_feedback
-  rating = app.screen(:rating) do |prompt|
-    if whatsapp?
-      # Rich interactive buttons for WhatsApp
-      prompt.select "Rate our service:", {
-        "5" => "⭐⭐⭐⭐⭐ Excellent",
-        "4" => "⭐⭐⭐⭐ Good", 
-        "3" => "⭐⭐⭐ Average",
-        "2" => "⭐⭐ Poor",
-        "1" => "⭐ Very Poor"
-      }
-    else
-      # Simple numbered list for USSD
-      prompt.select "Rate our service (1-5):", ["1", "2", "3", "4", "5"]
-    end
-  end
-  
-  app.say "Thank you for rating us #{rating} stars!"
-end
-
-private
-
-def whatsapp?
-  app.context["request.gateway"] == :whatsapp_cloud_api
-end
-```
-
-## Best Practices
-
-### Keep Methods Focused
-
-```ruby
-# ✅ Good: Single responsibility
-def collect_contact_info
-  name = app.screen(:name) { |p| p.ask "Name:" }
-  email = app.screen(:email) { |p| p.ask "Email:" }
-  { name: name, email: email }
-end
-
-# ❌ Avoid: Too much in one method
-def handle_everything
-  # 50+ lines of mixed logic
-end
-```
-
-### Use Meaningful Screen Names
-
-```ruby
-# ✅ Good: Descriptive names
-app.screen(:billing_address) { |p| p.ask "Billing address:" }
-app.screen(:confirm_payment) { |p| p.yes? "Confirm $#{amount}?" }
-
-# ❌ Avoid: Generic names  
-app.screen(:input1) { |p| p.ask "Address:" }
-app.screen(:confirm) { |p| p.yes? "OK?" }
-```
-
-### Handle Edge Cases
-
-```ruby
-def show_order_history
-  orders = fetch_user_orders
-  
-  if orders.empty?
-    app.say "You have no previous orders."
-    return
-  end
-  
-  choice = app.screen(:order) do |prompt|
-    prompt.select "Select order:", orders.map(&:display_name)
-  end
-  
-  show_order_details(orders.find { |o| o.display_name == choice })
-end
-```
-
-## Testing Flows
-
-See [Testing Guide](testing.md) for comprehensive testing strategies.