flow_chat 0.8.2 → 0.9.0

data/docs/factory-pattern.md

@@ -0,0 +1,355 @@
+# Factory Pattern
+
+The Factory pattern provides centralized processor configuration, eliminating duplication between webhook controllers and background jobs.
+
+## Quick Start
+
+### 1. Register Factories
+
+Register your processor configurations once in an initializer:
+
+```ruby
+# 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])
+  end
+  processor.run(WhatsAppFlow, :start)
+end
+
+FlowChat::Factory.register :intercom do |controller|
+  processor = FlowChat::Processor.new(controller) do |config|
+    config.use_gateway FlowChat::Intercom::Gateway::IntercomApi
+    config.use_session_store FlowChat::Session::CacheSessionStore
+    config.use_session_config(boundaries: [:conversation], identifier: :conversation_id)
+  end
+  processor.run(IntercomFlow, :start)
+end
+```
+
+### 2. Use in Controllers
+
+Execute factories directly in webhook controllers:
+
+```ruby
+# app/controllers/webhooks_controller.rb
+class WebhooksController < ApplicationController
+  def whatsapp
+    FlowChat::Factory.execute(:whatsapp, controller: self)
+  end
+
+  def intercom
+    FlowChat::Factory.execute(:intercom, controller: self)
+  end
+end
+```
+
+### 3. Use with Async (Recommended)
+
+Register factory with async support for background processing:
+
+```ruby
+# 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(factory: :whatsapp)  # Self-referencing for async
+  end
+  processor.run(WhatsAppFlow, :start)
+end
+
+# app/controllers/webhooks_controller.rb
+class WebhooksController < ApplicationController
+  def whatsapp
+    FlowChat::Factory.execute(:whatsapp, controller: self)
+  end
+end
+```
+
+**How it works:**
+1. Webhook receives request
+2. `use_async(factory: :whatsapp)` automatically uses `GenericAsyncJob`
+3. Job is enqueued with `factory: :whatsapp` parameter
+4. Background worker executes `FlowChat::Factory.execute(:whatsapp, controller: background_controller)`
+5. Flow processes in background with same configuration
+
+## Benefits
+
+### 1. Single Source of Truth
+
+Define processor configuration once, use everywhere:
+
+```ruby
+# Before: Duplicated configuration
+# 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_session_config(boundaries: [:flow])
+end
+
+# Background job (duplicate!)
+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])
+end
+
+# After: Single registration
+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])
+  end
+  processor.run(WhatsAppFlow, :start)
+end
+
+# Use everywhere with one line
+FlowChat::Factory.execute(:whatsapp, controller: self)
+```
+
+### 2. No Custom Job Classes
+
+For simple cases, use `GenericAsyncJob` automatically:
+
+```ruby
+# No need to create MyFlowJob class
+config.use_async(factory: :whatsapp)
+```
+
+### 3. Context-Aware Execution
+
+Same factory works in both webhook and background contexts:
+
+```ruby
+# Webhook context - processes inline or enqueues
+FlowChat::Factory.execute(:whatsapp, controller: webhook_controller)
+
+# Background context - always processes inline
+FlowChat::Factory.execute(:whatsapp, controller: background_controller)
+```
+
+Gateways automatically detect the context and prevent double-enqueueing.
+
+### 4. Easy Testing
+
+Test factories in isolation:
+
+```ruby
+RSpec.describe "WhatsApp Factory" do
+  it "executes successfully" do
+    controller = mock_controller
+    expect {
+      FlowChat::Factory.execute(:whatsapp, controller: controller)
+    }.not_to raise_error
+  end
+end
+```
+
+## API Reference
+
+### Registration
+
+**`FlowChat::Factory.register(name, &block)`**
+
+Register a factory with a given name.
+
+```ruby
+FlowChat::Factory.register :my_flow do |controller|
+  # Build and run processor
+  processor = FlowChat::Processor.new(controller) do |config|
+    # ... configuration
+  end
+  processor.run(MyFlow, :start)
+end
+```
+
+**Parameters:**
+- `name` (Symbol): Unique factory identifier
+- `block` (Proc): Factory block receiving `controller`
+
+**Returns:** `nil`
+
+### Execution
+
+**`FlowChat::Factory.execute(name, controller:)`**
+
+Execute a registered factory.
+
+```ruby
+FlowChat::Factory.execute(:my_flow, controller: self)
+```
+
+**Parameters:**
+- `name` (Symbol): Factory name to execute
+- `controller` (Object): Rails controller or BackgroundController
+
+**Returns:** Result of factory block
+
+**Raises:**
+- `FlowChat::Factory::FactoryNotFoundError` if factory not registered
+
+### Introspection
+
+**`FlowChat::Factory.registered?(name)`**
+
+Check if factory is registered.
+
+```ruby
+FlowChat::Factory.registered?(:whatsapp)  # => true
+```
+
+**`FlowChat::Factory.registered_factories`**
+
+Get all registered factory names.
+
+```ruby
+FlowChat::Factory.registered_factories  # => [:whatsapp, :intercom, :ussd]
+```
+
+**`FlowChat::Factory.clear!`**
+
+Clear all registered factories (primarily for testing).
+
+```ruby
+FlowChat::Factory.clear!
+```
+
+## Advanced Patterns
+
+### Environment-Specific Factories
+
+Create different configurations per environment:
+
+```ruby
+if Rails.env.production?
+  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
+    end
+    processor.run(ProductionFlow, :start)
+  end
+else
+  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::RailsSessionStore
+    end
+    processor.run(DevelopmentFlow, :start)
+  end
+end
+```
+
+### Multiple Variants
+
+Register multiple factories for the same platform:
+
+```ruby
+FlowChat::Factory.register :whatsapp_support do |controller|
+  processor = FlowChat::Processor.new(controller) do |config|
+    config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+    config.use_session_store FlowChat::Session::CacheSessionStore
+  end
+  processor.run(SupportFlow, :start)
+end
+
+FlowChat::Factory.register :whatsapp_sales do |controller|
+  processor = FlowChat::Processor.new(controller) do |config|
+    config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+    config.use_session_store FlowChat::Session::CacheSessionStore
+  end
+  processor.run(SalesFlow, :start)
+end
+
+# Use based on routing
+def whatsapp
+  factory = params[:department] == 'sales' ? :whatsapp_sales : :whatsapp_support
+  FlowChat::Factory.execute(factory, controller: self)
+end
+```
+
+### Accessing Request Data
+
+Factories receive the controller, which includes request data:
+
+```ruby
+FlowChat::Factory.register :whatsapp do |controller|
+  # Access request params
+  user_id = controller.params[:user_id]
+  platform = controller.request.headers["User-Agent"]
+
+  processor = FlowChat::Processor.new(controller) do |config|
+    config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+    config.use_session_store FlowChat::Session::CacheSessionStore
+  end
+
+  # Route to different flows based on params
+  flow = user_id.start_with?('premium_') ? PremiumFlow : StandardFlow
+  processor.run(flow, :start)
+end
+```
+
+## Migration Guide
+
+### From Duplicate Configuration
+
+**Before:**
+```ruby
+# Webhook controller
+class WebhooksController < ApplicationController
+  def whatsapp
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+      config.use_async(WhatsAppFlowJob)
+    end
+    processor.run(WhatsAppFlow, :start)
+  end
+end
+
+# Background job (duplicate!)
+class WhatsAppFlowJob < FlowChat::AsyncJob
+  def execute(controller, **job_params)
+    processor = FlowChat::Processor.new(controller) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+    processor.run(WhatsAppFlow, :start)
+  end
+end
+```
+
+**After:**
+```ruby
+# 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_async(factory: :whatsapp)  # Self-referencing for async
+  end
+  processor.run(WhatsAppFlow, :start)
+end
+
+# Webhook controller - ONE LINE!
+class WebhooksController < ApplicationController
+  def whatsapp
+    FlowChat::Factory.execute(:whatsapp, controller: self)
+  end
+end
+
+# No custom job class needed!
+```
+
+## See Also
+
+- [Async Background Processing](async-background-processing.md) - Using factories with async jobs
+- [Session Management](session-management.md) - Configuring session stores in factories
+- [Gateways](gateways.md) - Platform-specific gateway configuration

data/docs/gateway-context-variables.md

@@ -0,0 +1,171 @@
+# Gateway Context Variables
+
+This document describes all context variables set by each gateway in FlowChat.
+
+## All Context Variables
+
+| Variable | USSD Nalo | HTTP Simple | WhatsApp Cloud API | Telegram Bot API | Intercom API | Description |
+|----------|-----------|-------------|-------------------|------------------|--------------|-------------|
+| **Common Variables** |
+| `request.id` | ✓ Session ID | ✓ From user_params | ✓ Phone number | ✓ Chat ID | ✓ Conversation ID | Unique identifier for the session/conversation |
+| `request.user_id` | ✓ = msisdn | ✓ From user_params | ✓ Phone number | ✓ Telegram user ID | ✓ Contact ID | User/contact identifier |
+| `request.user_name` | ✗ | ✓ (optional) | ✓ (optional) | ✓ First + Last name | ✓ (optional) | User's display name |
+| `request.username` | ✗ | ✗ | ✗ | ✓ Telegram username | ✗ | Telegram @username |
+| `request.msisdn` | ✓ | ✓ (optional) | ✓ | ✗ | ✓ (optional) | E.164 phone number |
+| `request.email` | ✗ | ✓ (optional) | ✗ | ✗ | ✓ (optional) | User email |
+| `request.message_id` | ✓ UUID | ✓ UUID | ✓ WhatsApp ID | ✓ Telegram msg ID | ✓ (optional) | Message identifier |
+| `request.timestamp` | ✓ Current | ✓ Current | ✓ Current | ✓ From message | ✓ Current | ISO8601 timestamp |
+| `request.gateway` | ✓ `:nalo` | ✓ `:http_simple` | ✓ `:whatsapp_cloud_api` | ✓ `:telegram_bot_api` | ✓ `:intercom_api` | Gateway name |
+| `request.platform` | ✓ `:ussd` | ✓ `:http` | ✓ `:whatsapp` | ✓ `:telegram` | ✓ `:intercom` | Platform type |
+| `request.body` | ✓ | ✓ | ✓ | ✓ | ✓ | Raw request body (stringified keys) |
+| `request.input` | ✓ Text | ✓ Text | ✓ Varies⁴ | ✓ Varies⁶ | ✓ Text/nil⁵ | User's input message |
+| **WhatsApp-Specific** |
+| `request.location` | ✗ | ✗ | ✓ | ✓ | ✗ | Location data (when input is `"$location$"`) |
+| `request.media` | ✗ | ✗ | ✓ | ✓ | ✗ | Media metadata (when input is `"$media$"`) |
+| `request.contact` | ✗ | ✗ | ✗ | ✓ | ✗ | Contact data (when input is `"$contact$"`) |
+| `whatsapp.business.phone_number` | ✗ | ✗ | ✓ | ✗ | ✗ | Business phone number (E.164) |
+| `whatsapp.business.phone_number_id` | ✗ | ✗ | ✓ | ✗ | ✗ | WhatsApp phone number ID |
+| `whatsapp.client` | ✗ | ✗ | ✓ | ✗ | ✗ | WhatsApp client instance |
+| **Telegram-Specific** |
+| `telegram.client` | ✗ | ✗ | ✗ | ✓ | ✗ | Telegram client instance |
+| `telegram.chat_type` | ✗ | ✗ | ✗ | ✓ | ✗ | Chat type (private, group, supergroup, channel) |
+| `telegram.callback_query_id` | ✗ | ✗ | ✗ | ✓ (callbacks) | ✗ | Callback query ID for inline keyboard responses |
+| `telegram.original_message_id` | ✗ | ✗ | ✗ | ✓ (callbacks) | ✗ | Original message ID that triggered callback |
+| **HTTP-Specific** |
+| `http.method` | ✗ | ✓ | ✗ | ✗ | ✗ | HTTP method (GET/POST) |
+| `http.path` | ✗ | ✓ | ✗ | ✗ | ✗ | Request path |
+| `http.user_agent` | ✗ | ✓ | ✗ | ✗ | ✗ | User agent header |
+| **Intercom-Specific** |
+| `intercom.client` | ✗ | ✗ | ✗ | ✗ | ✓ | Intercom client instance |
+| `intercom.topic` | ✗ | ✗ | ✗ | ✗ | ✓ | Webhook event type |
+
+
+## Accessing Variables in Flows
+
+```ruby
+class MyFlow < FlowChat::Flow
+  def start
+    # Common variables (all gateways)
+    user_id = app.context["request.user_id"]
+    user_name = app.context["request.user_name"]  # Available from WhatsApp, Intercom, HTTP (optional)
+    msisdn = app.context["request.msisdn"]        # Available from USSD, WhatsApp, HTTP (optional)
+    email = app.context["request.email"]          # Available from HTTP (optional)
+    platform = app.context["request.platform"]
+    input = app.context["request.input"]
+
+    # Or use convenience methods
+    user_id = app.user_id
+    platform = app.platform
+    input = app.input
+
+    # Platform-specific variables
+    case app.platform
+    when :whatsapp
+      client = app.context["whatsapp.client"]
+
+      # Handle special input types
+      if input == "$location$"
+        location = app.context["request.location"]
+        lat = location[:latitude]
+        lng = location[:longitude]
+      end
+
+    when :telegram
+      client = app.context["telegram.client"]
+      chat_type = app.context["telegram.chat_type"]
+      username = app.context["request.username"]  # @username
+
+      # Handle special input types
+      case input
+      when "$location$"
+        location = app.context["request.location"]
+        lat = location["latitude"]
+        lng = location["longitude"]
+      when "$media$"
+        media = app.context["request.media"]
+        file_id = media[:file_id]
+        media_type = media[:type]  # :photo, :document, :voice
+      when "$contact$"
+        contact = app.context["request.contact"]
+        phone = contact[:phone_number]
+      end
+
+    when :intercom
+      topic = app.context["intercom.topic"]
+      client = app.context["intercom.client"]
+
+      # Handle events without messages
+      if input.nil?
+        # Event without user message (e.g., admin-initiated)
+      end
+
+    when :http
+      method = app.context["http.method"]
+      user_agent = app.context["http.user_agent"]
+
+    when :ussd
+      msisdn = app.context["request.msisdn"]
+    end
+  end
+end
+```
+
+## Notes
+
+⁴ **WhatsApp input**: Text for text messages, `"$location$"` for location, `"$media$"` for media (image, document, audio, video, sticker), `"$contact$"` for shared contacts, or button/list reply IDs.
+
+⁵ **Intercom input**: Text content or `nil` for events without user messages.
+
+⁶ **Telegram input**: Text for text messages, callback data for inline keyboard responses, `"$location$"` for location, `"$media$"` for media (photo, video, audio, document, voice, sticker), `"$contact$"` for shared contacts.
+
+## Media Type Reference
+
+Both WhatsApp and Telegram set `request.media` with a `:type` symbol when media is received:
+
+| Media Type | WhatsApp | Telegram | Additional Fields |
+|------------|----------|----------|-------------------|
+| `:image` / `:photo` | ✓ `:image` | ✓ `:photo` | id/file_id, mime_type, width, height |
+| `:video` | ✓ | ✓ | id/file_id, mime_type, duration, width, height |
+| `:audio` | ✓ | ✓ | id/file_id, mime_type, duration, title, performer |
+| `:voice` | ✗ | ✓ | file_id, mime_type, duration |
+| `:document` | ✓ | ✓ | id/file_id, mime_type, filename |
+| `:sticker` | ✓ | ✓ | id/file_id, emoji, set_name, is_animated |
+
+### Accessing Media in Flows
+
+FlowChat provides constants for special input markers:
+
+```ruby
+FlowChat::Input::LOCATION  # "$location$"
+FlowChat::Input::MEDIA     # "$media$"
+FlowChat::Input::CONTACT   # "$contact$"
+FlowChat::Input::START     # "$start$" (session marker)
+```
+
+Example usage:
+
+```ruby
+case app.input
+when FlowChat::Input::MEDIA
+  media = app.context["request.media"]
+
+  case media[:type]
+  when :photo, :image
+    file_id = media[:file_id] || media[:id]
+  when :video
+    duration = media[:duration]
+  when :document
+    filename = media[:file_name] || media[:filename]
+  when :sticker
+    emoji = media[:emoji]
+  end
+
+when FlowChat::Input::LOCATION
+  location = app.context["request.location"]
+  lat, lng = location["latitude"], location["longitude"]
+
+when FlowChat::Input::CONTACT
+  contact = app.context["request.contact"]
+  phone = contact[:phone_number]
+end
+```