flow_chat 0.8.1 → 0.9.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flow_chat
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-14 00:00:00.000000000 Z
+date: 2026-07-09 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,15 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".DS_Store"
+- ".cliff.toml"
 - ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
 - ".gitignore"
 - ".ruby-version"
+- ".standard.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -102,63 +150,82 @@ files:
 - SECURITY.md
 - bin/console
 - bin/setup
+- docs/architecture.md
+- docs/async-background-processing.md
 - docs/configuration.md
-- docs/flows.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/telegram.md
+- docs/platforms/ussd.md
+- docs/platforms/whatsapp.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/config.rb
 - lib/flow_chat/context.rb
+- lib/flow_chat/executor.rb
+- lib/flow_chat/factory.rb
 - lib/flow_chat/flow.rb
+- lib/flow_chat/gateway_async_support.rb
+- lib/flow_chat/generic_async_job.rb
+- lib/flow_chat/http/gateway/simple.rb
+- lib/flow_chat/http/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/gateway/intercom_api.rb
+- lib/flow_chat/intercom/renderer.rb
 - lib/flow_chat/interrupt.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/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/gateway/bot_api.rb
+- lib/flow_chat/telegram/middleware/choice_mapper.rb
+- lib/flow_chat/telegram/renderer.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/gateway/cloud_api.rb
-- lib/flow_chat/whatsapp/middleware/executor.rb
-- lib/flow_chat/whatsapp/processor.rb
+- lib/flow_chat/whatsapp/id_generator.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
 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. 

data/docs/media.md

@@ -1,153 +0,0 @@
-# Media Support
-
-FlowChat supports rich media attachments for enhanced conversational experiences with automatic cross-platform optimization.
-
-## Supported Media Types
-
-- **📷 Images** (`type: :image`) - Photos, screenshots, diagrams
-- **📄 Documents** (`type: :document`) - PDFs, forms, receipts  
-- **🎥 Videos** (`type: :video`) - Tutorials, demos, explanations
-- **🎵 Audio** (`type: :audio`) - Voice messages, recordings
-- **😊 Stickers** (`type: :sticker`) - Fun visual elements
-
-## Basic Usage
-
-```ruby
-class ProductFlow < FlowChat::Flow
-  def main_page
-    # Text input with context image
-    feedback = app.screen(:feedback) do |prompt|
-      prompt.ask "What do you think of our new product?",
-        media: {
-          type: :image,
-          url: "https://cdn.example.com/products/new_product.jpg"
-        }
-    end
-
-    # Send informational media
-    app.say "Thanks for your feedback! Here's what's coming next:",
-      media: {
-        type: :video,
-        url: "https://videos.example.com/roadmap.mp4"
-      }
-
-    # Document with filename
-    app.say "Here's your receipt:",
-      media: {
-        type: :document,
-        url: "https://api.example.com/receipt.pdf",
-        filename: "receipt.pdf"
-      }
-  end
-end
-```
-
-## Media Hash Format
-
-```ruby
-{
-  type: :image,        # Required: :image, :document, :audio, :video, :sticker
-  url: "https://...",  # Required: URL to the media file OR WhatsApp media ID
-  filename: "doc.pdf"  # Optional: Only for documents
-}
-```
-
-## Using WhatsApp Media IDs
-
-For better performance and to avoid external dependencies, you can upload files to WhatsApp and use the media ID:
-
-```ruby
-# Upload a file first
-client = FlowChat::Whatsapp::Client.new(config)
-media_id = client.upload_media('path/to/image.jpg', 'image/jpeg')
-
-# Then use the media ID in your flow
-app.screen(:product_demo) do |prompt|
-  prompt.ask "What do you think?",
-    media: {
-      type: :image,
-      url: media_id  # Use the media ID instead of URL
-    }
-end
-```
-
-## WhatsApp Client Media Methods
-
-The WhatsApp client provides methods for uploading and sending media:
-
-```ruby
-client = FlowChat::Whatsapp::Client.new(config)
-
-# Upload media and get media ID
-media_id = client.upload_media('image.jpg', 'image/jpeg')
-media_id = client.upload_media(file_io, 'image/jpeg', 'photo.jpg')
-
-# Send media directly
-client.send_image("+1234567890", "https://example.com/image.jpg", "Caption")
-client.send_image("+1234567890", media_id, "Caption")
-
-# Send document with MIME type and filename
-client.send_document("+1234567890", "https://example.com/doc.pdf", "Your receipt", "receipt.pdf", "application/pdf")
-
-# Send other media types
-client.send_video("+1234567890", "https://example.com/video.mp4", "Demo video", "video/mp4")
-client.send_audio("+1234567890", "https://example.com/audio.mp3", "audio/mpeg")
-client.send_sticker("+1234567890", "https://example.com/sticker.webp", "image/webp")
-```
-
-## Cross-Platform Behavior
-
-### WhatsApp Experience
-- Media is sent directly to the chat
-- Prompt text becomes the media caption
-- Rich, native messaging experience
-
-### USSD Experience  
-- Media URL is included in text message
-- Graceful degradation with clear media indicators
-- Users can access media via the provided link
-
-```ruby
-# This code works on both platforms:
-app.screen(:help) do |prompt|
-  prompt.ask "Describe your issue:",
-    media: {
-      type: :image,
-      url: "https://support.example.com/help_example.jpg"
-    }
-end
-```
-
-**WhatsApp Result:** Image sent with caption "Describe your issue:"
-
-**USSD Result:** 
-```
-📷 Image: https://support.example.com/help_example.jpg
-
-Describe your issue:
-```
-
-## Advanced Examples
-
-### Dynamic Media Based on User Context
-
-```ruby
-class SupportFlow < FlowChat::Flow
-  def show_help
-    user_level = determine_user_level
-    
-    help_media = case user_level
-    when :beginner
-      { type: :video, url: "https://help.example.com/beginner_guide.mp4" }
-    when :advanced
-      { type: :document, url: "https://help.example.com/advanced_manual.pdf", filename: "advanced_manual.pdf" }
-    else
-      { type: :image, url: "https://help.example.com/quick_reference.jpg" }
-    end
-    
-    app.say "Here's help tailored for you:", media: help_media
-  end
-end
-```
-
-See [examples/whatsapp_media_examples.rb](../examples/whatsapp_media_examples.rb) for complete media implementation examples.