flow_chat 0.8.2 → 0.10.0

data/docs/configuration.md

@@ -1,360 +1,183 @@
-# Configuration Reference
+# Configuration
 
-This document covers all FlowChat configuration options.
+FlowChat has two layers of configuration: global settings on `FlowChat::Config`, set once during boot, and per-processor settings passed to the `FlowChat::Processor.new` block for each webhook.
 
-## Framework Configuration
+## Global configuration
 
-```ruby
-# config/initializers/flowchat.rb
-
-# Core configuration
-FlowChat::Config.logger = Rails.logger
-FlowChat::Config.cache = Rails.cache
-FlowChat::Config.simulator_secret = "your_secure_secret_here"
-
-# Validation error display behavior
-FlowChat::Config.combine_validation_error_with_message = true  # default
+Set these once, for example in `config/initializers/flow_chat.rb`.
 
-# Setup instrumentation (optional)
-FlowChat.setup_instrumentation!
-```
-
-## Session Configuration
+| Option | Default | What it controls |
+|---|---|---|
+| `FlowChat::Config.logger` | `Logger.new($stdout)` | The logger FlowChat writes to. Set it to `Rails.logger` to fold FlowChat logs into your app's. |
+| `FlowChat::Config.cache` | `nil` | The cache backend the session store reads and writes. Required: `CacheSessionStore` raises without it. Set it to `Rails.cache` or any store with the same interface. |
+| `FlowChat::Config.simulator_secret` | `nil` | Secret that enables the local web simulator. The simulator stays off until this is set. See [testing.md](testing.md). |
+| `FlowChat::Config.combine_validation_error_with_message` | `true` | When `true`, a rejected input re-prompts with the validation error followed by the original prompt. When `false`, only the error is shown. |
+| `FlowChat::Config.inject_middleware_logger` | `true` in Rails development, else `false` | Whether a logging middleware is inserted into the stack automatically. |
 
 ```ruby
-# Session boundaries control how session IDs are constructed
-FlowChat::Config.session.boundaries = [:flow, :platform]  # default
-FlowChat::Config.session.hash_identifiers = true          # hash identifiers for privacy
-FlowChat::Config.session.identifier = nil                 # let platforms choose (default)
-
-# Available boundary options:
-# :flow - separate sessions per flow class
-# :platform - separate sessions per platform (ussd, whatsapp)  
-# :gateway - separate sessions per gateway
-# [] - global sessions (no boundaries)
-
-# Available identifier options:
-# nil - platform chooses default (:request_id for USSD, :msisdn for WhatsApp)
-# :msisdn - use phone number (durable sessions)
-# :request_id - use request ID (ephemeral sessions)
+# config/initializers/flow_chat.rb
+FlowChat::Config.cache = Rails.cache
+FlowChat::Config.logger = Rails.logger
+FlowChat::Config.simulator_secret = Rails.application.credentials.flow_chat_simulator_secret
 ```
 
-## USSD Configuration
+## USSD configuration
 
-```ruby
-# USSD pagination settings
-FlowChat::Config.ussd.pagination_page_size = 140          # characters per page
-FlowChat::Config.ussd.pagination_next_option = "#"        # option to go to next page
-FlowChat::Config.ussd.pagination_next_text = "More"       # text for next option
-FlowChat::Config.ussd.pagination_back_option = "0"        # option to go back
-FlowChat::Config.ussd.pagination_back_text = "Back"       # text for back option
-```
+`FlowChat::Config.ussd` controls how USSD responses are paginated. USSD messages are length-limited, so FlowChat splits long output into pages and adds navigation options.
 
-## WhatsApp Configuration
+| Option | Default | What it controls |
+|---|---|---|
+| `pagination_page_size` | `140` | Maximum characters per USSD page before FlowChat splits the response. |
+| `pagination_next_option` | `"#"` | The input a user sends to see the next page. |
+| `pagination_next_text` | `"More"` | The label shown next to the next-page option. |
+| `pagination_back_option` | `"0"` | The input a user sends to go to the previous page. |
+| `pagination_back_text` | `"Back"` | The label shown next to the previous-page option. |
 
 ```ruby
-# Message handling modes
-FlowChat::Config.whatsapp.message_handling_mode = :inline  # :inline, :background, :simulator
-FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+FlowChat::Config.ussd.pagination_page_size = 160
 ```
 
-### WhatsApp Credential Configuration
+## WhatsApp configuration
 
-#### Option 1: Rails Credentials
+`FlowChat::Config.whatsapp` holds the WhatsApp Cloud API base URL. Per-tenant credentials (access token, phone number id, app secret, verify token) are passed to the gateway, not set here. See [platforms/whatsapp.md](platforms/whatsapp.md).
 
-```bash
-rails credentials:edit
-```
+| Option | Default | What it controls |
+|---|---|---|
+| `api_base_url` | `"https://graph.facebook.com/v23.0"` | The Cloud API version and host the WhatsApp client calls. |
 
-```yaml
-whatsapp:
-  access_token: "your_access_token"
-  phone_number_id: "your_phone_number_id"
-  verify_token: "your_verify_token"
-  app_id: "your_app_id"
-  app_secret: "your_app_secret"
-  business_account_id: "your_business_account_id"
-  skip_signature_validation: false
-```
+## HTTP configuration
 
-#### Option 2: Environment Variables
+`FlowChat::Config.http` holds defaults for the HTTP gateway used in testing and custom integrations. See the platform guides for the full request and response shapes.
 
-```bash
-export WHATSAPP_ACCESS_TOKEN="your_access_token"
-export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id" 
-export WHATSAPP_VERIFY_TOKEN="your_verify_token"
-export WHATSAPP_APP_ID="your_app_id"
-export WHATSAPP_APP_SECRET="your_app_secret"
-export WHATSAPP_BUSINESS_ACCOUNT_ID="your_business_account_id"
-export WHATSAPP_SKIP_SIGNATURE_VALIDATION="false"
-```
+| Option | Default | What it controls |
+|---|---|---|
+| `default_gateway` | `:simple` | The HTTP gateway used when none is named. |
+| `request_timeout` | `30` | Request timeout in seconds. |
+| `response_format` | `:json` | The response serialization format. |
 
-#### Option 3: Programmatic Configuration
+## Sessions
 
-```ruby
-config = FlowChat::Whatsapp::Configuration.new(:my_config)  # Named configuration
-config.access_token = "your_access_token"
-config.phone_number_id = "your_phone_number_id"
-config.verify_token = "your_verify_token"
-config.app_id = "your_app_id"
-config.app_secret = "your_app_secret"
-config.business_account_id = "your_business_account_id"
-config.skip_signature_validation = false
-# Configuration is automatically registered as :my_config
-```
+A session holds the answers a flow has collected so far. FlowChat looks the session up by an id it builds on every request from two things: a set of boundaries and an identifier.
 
-**⚠️ Important for Background Jobs:** When using background mode with programmatic configurations, you must register them in an initializer:
+`FlowChat::Config.session` sets the defaults.
 
-```ruby
-# config/initializers/whatsapp_configs.rb
-# Register configurations so background jobs can access them
-production_config = FlowChat::Whatsapp::Configuration.new(:production)
-production_config.access_token = ENV['PROD_WHATSAPP_TOKEN']
-# ... other settings
-
-staging_config = FlowChat::Whatsapp::Configuration.new(:staging)  
-staging_config.access_token = ENV['STAGING_WHATSAPP_TOKEN']
-# ... other settings
-```
+| Option | Default | What it controls |
+|---|---|---|
+| `boundaries` | `[:flow, :gateway, :platform]` | Which dimensions separate one session from another (see below). |
+| `hash_identifiers` | `true` | Whether the identifier (often a phone number) is hashed into the session id rather than stored in the clear. |
+| `identifier` | `nil` | Which request value identifies the user. `nil` lets the platform choose: WhatsApp uses `:msisdn`, the others use `:request_id`. |
+| `session_id_proc` | `nil` | A callable that builds the session id from the context directly, bypassing boundaries and identifier. |
 
-Then use named configurations in controllers:
+### How the session id is built
 
-```ruby
-# Use registered configuration
-config = FlowChat::Whatsapp::Configuration.get(:production)
-processor = FlowChat::Whatsapp::Processor.new(self) do |config|
-  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, config
-end
-```
-
-## Security Configuration
+FlowChat sets the session id one of three ways, in order of precedence:
 
-### WhatsApp Security
-
-```ruby
-# Production security (recommended)
-config.app_secret = "your_whatsapp_app_secret"
-config.skip_signature_validation = false  # default
+1. If `context["session.id"]` is already set, that value is used verbatim (a manual override).
+2. If you passed a block to `use_session_config`, its return value is used verbatim. Boundaries and identifier are skipped entirely.
+3. Otherwise the id is built from the boundaries and the identifier, described below.
 
-# Development mode (disable validation)
-config.app_secret = nil
-config.skip_signature_validation = true
-```
-
-### Simulator Security
-
-```ruby
-# Use Rails secret for uniqueness
-FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_simulator"
+Think of the built id as `boundaries` followed by `identifier`: the boundaries describe the context a session lives in (the walls that separate it), and the identifier is who the session belongs to. The parts are joined with `:` in this fixed order, and a part is included only when its boundary is enabled and its value is present:
 
-# Or use dedicated secret
-FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
 ```
-
-## Environment-Specific Configuration
-
-```ruby
-# config/initializers/flowchat.rb
-case Rails.env
-when 'development'
-  FlowChat::Config.whatsapp.message_handling_mode = :simulator
-  FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_dev"
-  
-when 'test'
-  FlowChat::Config.whatsapp.message_handling_mode = :simulator
-  FlowChat::Config.simulator_secret = "test_secret"
-  
-when 'staging'
-  FlowChat::Config.whatsapp.message_handling_mode = :inline
-  FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
-  
-when 'production'
-  FlowChat::Config.whatsapp.message_handling_mode = :background
-  FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
-  FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
-end
+flow_name : platform : gateway : url : identifier
 ```
 
-## Processor Configuration
-
-### USSD Processor
+The order of the parts is fixed regardless of the order you list boundaries in. With the default boundaries `[:flow, :gateway, :platform]`, a WhatsApp user in `RegistrationFlow` gets:
 
-```ruby
-processor = FlowChat::Ussd::Processor.new(self) do |config|
-  # Gateway (required)
-  config.use_gateway FlowChat::Ussd::Gateway::Nalo
-  
-  # Session storage (required)
-  config.use_session_store FlowChat::Session::CacheSessionStore
-  
-  # Optional middleware
-  config.use_middleware MyCustomMiddleware
-  
-  # Configure session boundaries
-  config.use_session_config(
-    boundaries: [:flow, :platform],     # which boundaries to enforce
-    hash_identifiers: true,             # hash identifiers for privacy
-    identifier: :msisdn                 # use MSISDN for durable sessions (optional)
-  )
-  
-  # Shorthand for durable sessions (identifier: :msisdn)
-  config.use_durable_sessions
-end
 ```
-
-### WhatsApp Processor
-
-```ruby
-processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: Rails.env.development?) do |config|
-  # Gateway (required)
-  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-  
-  # Session storage (required)  
-  config.use_session_store FlowChat::Session::CacheSessionStore
-  
-  # Optional custom configuration
-  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, custom_whatsapp_config
-end
+registration_flow:whatsapp:whatsapp_cloud_api:9f86d0818...
+     (flow)          (platform)     (gateway)   (hashed msisdn)
 ```
 
-## Session Store Options
+The hashed identifier is shown truncated here for readability; the real key carries the 32-character (128-bit) SHA256 prefix.
 
-### Cache Session Store
+### What each boundary isolates
 
-```ruby
-config.use_session_store FlowChat::Session::CacheSessionStore
-```
+A boundary is a wall. Include it and two requests that differ on that dimension get separate sessions; drop it and they share one session, provided the identifier matches.
 
-Uses Rails cache backend with automatic TTL management. This is the primary session store available in FlowChat.
+| Boundary | Segment | Adding it separates sessions by | Drop it when |
+|---|---|---|---|
+| `:flow` | `context["flow.name"]` | flow class, so `RegistrationFlow` and `SurveyFlow` never share state | you want one session shared across all flows (rare) |
+| `:platform` | `:ussd`, `:whatsapp`, and so on | platform, so the same person on USSD and on WhatsApp gets two sessions | you want one conversation to span platforms |
+| `:gateway` | `:nalo`, `:whatsapp_cloud_api`, and so on | gateway, so two gateways on the same platform (for example two USSD aggregators) do not collide | you are consolidating gateways and want them to share |
+| `:url` | normalized `host + path` | host and path, for per-tenant or per-endpoint isolation (`tenant1.app.com` vs `tenant2.app.com`) | single tenant, single endpoint |
 
-## Middleware Configuration
+The `:url` segment is `host + path` with the leading slash removed and any character outside `[a-zA-Z0-9._-]` replaced by `_`. If that exceeds 50 characters it becomes the first 41 characters plus an 8-character SHA256 suffix, so it stays bounded but still recognizable.
 
-### Built-in Middleware
+### The identifier
 
-```ruby
-# Pagination (USSD only, automatic)
-FlowChat::Ussd::Middleware::Pagination
+The identifier is chosen independently of the boundaries and always comes last. Its type is the `identifier` option, or a platform default when unset: WhatsApp uses `:msisdn`, every other platform uses `:request_id`.
 
-# Session management (automatic)
-FlowChat::Session::Middleware
+| Type | Value | Hashed |
+|---|---|---|
+| `:request_id` | `context["request.id"]` | Never. It is already opaque. On USSD it is the telco session id, which rotates on timeout, so the session is ephemeral. |
+| `:msisdn` | `context["request.msisdn"]` | Yes, when `hash_identifiers` is true (the default): the first 32 hex characters of SHA256 (128 bits). |
+| `:user_id` | `context["request.user_id"]` | Yes, when `hash_identifiers` is true. |
 
-# Gateway communication (automatic)
-FlowChat::Ussd::Gateway::Nalo
-FlowChat::Whatsapp::Gateway::CloudApi
-```
+So with the default `hash_identifiers: true`, a phone number never appears in the session key in the clear, while a `request_id` passes through untouched.
 
-### Custom Middleware
+### Worked examples
 
-```ruby
-class LoggingMiddleware
-  def initialize(app)
-    @app = app
-  end
-
-  def call(context)
-    Rails.logger.info "Processing request: #{context.input}"
-    result = @app.call(context)
-    Rails.logger.info "Response: #{result[1]}"
-    result
-  end
-end
+Default config, USSD, `RegistrationFlow`, no durable sessions. The identifier is `:request_id`, the telco session id, so the session lasts only as long as that telco session:
 
-# Use custom middleware
-config.use_middleware LoggingMiddleware
+```
+registration_flow:ussd:nalo:1699_telco_session_42
 ```
 
-## Validation Configuration
-
-### Error Display Options
+The same, but with `use_durable_sessions` (identifier `:user_id`, which Nalo sets equal to the msisdn) and hashing on. Now the user can time out and dial back into the same session:
 
-```ruby
-# Combine validation error with original message (default)
-FlowChat::Config.combine_validation_error_with_message = true
-# User sees: "Invalid email format\n\nEnter your email:"
-
-# Show only validation error
-FlowChat::Config.combine_validation_error_with_message = false
-# User sees: "Invalid email format"
+```
+registration_flow:ussd:nalo:9f86d0818...
 ```
 
-## Background Job Configuration
+### Configuring sessions per processor
 
-### Job Class Setup
+Set boundaries, identifier, and hashing directly:
 
 ```ruby
-# app/jobs/whatsapp_message_job.rb
-class WhatsappMessageJob < ApplicationJob
-  include FlowChat::Whatsapp::SendJobSupport
-
-  def perform(send_data)
-    perform_whatsapp_send(send_data)
-  end
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  config.use_session_config(boundaries: [:flow, :platform], identifier: :msisdn, hash_identifiers: true)
 end
 ```
 
-**Configuration Resolution:** The job automatically resolves configurations using:
-1. Named configuration from `send_data[:configuration_name]` if present
-2. Default configuration from credentials/environment variables
-
-For custom resolution logic, override the configuration resolution:
+Or take full control of the id with a block:
 
 ```ruby
-class CustomWhatsappMessageJob < ApplicationJob
-  include FlowChat::Whatsapp::SendJobSupport
-
-  def perform(send_data)
-    perform_whatsapp_send(send_data)
-  end
-
-  private
-
-  def resolve_whatsapp_configuration(send_data)
-    # Custom logic to resolve configuration
-    tenant_id = ...
-    FlowChat::Whatsapp::Configuration.get("tenant_#{tenant_id}")
-  end
+config.use_session_config do |context|
+  "tenant:#{context["request.tenant_id"]}:#{context["request.msisdn"]}"
 end
 ```
 
-### Queue Configuration
+Three convenience methods wrap common changes:
 
-```ruby
-# config/application.rb
-config.active_job.queue_adapter = :sidekiq
+| Method | Effect |
+|---|---|
+| `use_durable_sessions` | Sets the identifier to `:user_id`, a stable per-user id. It changes only the identifier, not the boundaries. It matters most on USSD, where `:request_id` rotates on timeout but `:user_id` (which Nalo sets equal to the msisdn) is stable, so the conversation survives a rotation. |
+| `use_cross_platform_sessions` | Narrows boundaries to `[:flow]`, dropping platform and gateway, so one user shares a single session across platforms. |
+| `use_url_isolation` | Appends `:url` to the current boundaries for per-tenant or per-host isolation. |
 
-# config/initializers/flowchat.rb
-FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+```ruby
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  config.use_durable_sessions
+end
 ```
 
-## Instrumentation Configuration
-
-### Basic Setup
+One subtlety with `use_cross_platform_sessions`: dropping the `:platform` boundary only shares a session if the identifier resolves to the same value on both platforms. The platform default identifier differs (WhatsApp uses `:msisdn`, USSD uses `:request_id`), so for real cross-platform sharing pair it with a stable identifier, either `use_durable_sessions` (`:user_id`) or `identifier: :msisdn`.
 
-```ruby
-# Enable instrumentation
-FlowChat.setup_instrumentation!
-```
+## Async processing
 
-### Custom Event Subscribers
+Enable background processing with `use_async`. It has two forms:
 
 ```ruby
-# Subscribe to specific events
-ActiveSupport::Notifications.subscribe("flow.execution.end.flow_chat") do |event|
-  # Custom handling
-  ExternalMonitoring.track_flow_execution(
-    event.payload[:flow_name], 
-    event.duration
-  )
-end
+# Use a factory (no custom job class needed). The factory: keyword is required.
+config.use_async(factory: :whatsapp)
 
-# Subscribe to all FlowChat events
-ActiveSupport::Notifications.subscribe(/\.flow_chat$/) do |name, start, finish, id, payload|
-  CustomLogger.log_event(name, payload.merge(duration: finish - start))
-end
+# Or use your own ActiveJob subclass, with optional job params.
+config.use_async(MyFlowJob, deployment_id: 123)
 ```
 
-## Configuration Validation
-
-FlowChat validates configuration at runtime and provides helpful error messages:
-
-FlowChat validates configuration at runtime and provides helpful error messages for missing or invalid configurations. 
+The webhook enqueues the job and returns immediately; the job re-runs the flow in the background. USSD does not support async, since its protocol needs a synchronous response. See [factory-pattern.md](factory-pattern.md) and [async-background-processing.md](async-background-processing.md).

data/docs/factory-pattern.md

@@ -0,0 +1,58 @@
+# Factory pattern
+
+A factory is a named block that builds and runs a processor. You register it once, then call it by name from both the webhook and the background job. This keeps the processor configuration in one place, so the two contexts cannot drift apart.
+
+Without a factory, a webhook that enqueues a background job needs the same processor setup written twice: once in the controller and once in the job. A factory removes the duplication.
+
+## Registering and executing
+
+Register the factory 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_async(factory: :whatsapp)
+  end
+  processor.run(WhatsAppFlow, :start)
+end
+```
+
+Execute it from the webhook controller:
+
+```ruby
+# app/controllers/whatsapp_controller.rb
+class WhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    FlowChat::Factory.execute(:whatsapp, controller: self)
+  end
+end
+```
+
+The block receives a controller and returns whatever `processor.run` returns. Executing an unregistered name raises `FlowChat::Factory::FactoryNotFoundError`.
+
+## How it pairs with async
+
+Notice the factory references itself: `config.use_async(factory: :whatsapp)`. That closes the loop.
+
+1. The webhook calls `Factory.execute(:whatsapp, controller: self)`.
+2. The factory builds a processor with `use_async(factory: :whatsapp)`, so the gateway enqueues `FlowChat::GenericAsyncJob` with `factory: :whatsapp` and returns immediately.
+3. The background job calls `Factory.execute(:whatsapp, controller: background_controller)` again.
+4. This time the gateway is running in the background, so it processes the flow inline and sends the reply.
+
+The same factory builds the processor in both passes, so there is one definition of the gateway, session store, and flow. See [async-background-processing.md](async-background-processing.md) for what happens inside the job.
+
+## Other methods
+
+- `FlowChat::Factory.registered?(:whatsapp)` returns whether a name is registered.
+- `FlowChat::Factory.registered_factories` lists the registered names.
+- `FlowChat::Factory.clear!` removes all registrations (useful in tests).
+
+## Related
+
+- [Async and background processing](async-background-processing.md)
+- [Configuration](configuration.md#async-processing)