flow_chat 0.9.0 → 0.10.0

data/docs/getting-started.md

@@ -1,429 +1,90 @@
-# Getting Started with FlowChat
+# Getting Started
 
-This guide will walk you through setting up FlowChat and building your first conversational application that works across multiple platforms.
+This guide takes you from an empty Rails app to a running FlowChat flow. It reuses the same flow and processor shown in the [README](../README.md).
 
 ## Prerequisites
 
-- Ruby 2.3+ (Ruby 3.0+ recommended)
-- Rails 6.0+ (Rails 7.0+ recommended)
-- Basic understanding of Rails controllers and routing
+- A Rails application.
+- Ruby 3.0 or newer.
+- A cache the session store can use, such as `Rails.cache`.
 
-## Installation
+## Install
 
-Add FlowChat to your Rails application:
+Add the gem to your Gemfile:
 
 ```ruby
-# Gemfile
-gem 'flow_chat'
+gem "flow_chat"
 ```
 
-```bash
-bundle install
-```
-
-## Quick Start: Your First Multi-Platform App
-
-Let's build a simple survey application that works across USSD, WhatsApp, Telegram, and HTTP APIs.
+Then run `bundle install`. There are no migrations and no generators to run.
 
-### 1. Create the Flow
+## Configure the cache
 
-Create a new file `app/flow_chat/survey_flow.rb`:
+The cache-backed session store needs a cache. Set it once during boot, for example in an initializer:
 
 ```ruby
-class SurveyFlow < FlowChat::Flow
-  def start
-    # Welcome message that works on all platforms
-    name = app.screen(:name) do |prompt|
-      prompt.ask "Welcome to our survey! What's your name?",
-        validate: ->(input) {
-          return "Name must be at least 2 characters" if input.length < 2
-          nil
-        },
-        transform: ->(input) { input.strip.titleize }
-    end
-
-    # Rating question with platform-appropriate choices
-    rating = app.screen(:rating) do |prompt|
-      prompt.select "Hi #{name}! Rate our service:", {
-        "5" => "⭐⭐⭐⭐⭐ Excellent",
-        "4" => "⭐⭐⭐⭐ Good", 
-        "3" => "⭐⭐⭐ Average",
-        "2" => "⭐⭐ Poor",
-        "1" => "⭐ Very Poor"
-      }
-    end
-
-    # Feedback collection
-    feedback = app.screen(:feedback) do |prompt|
-      prompt.ask "Any additional feedback?",
-        validate: ->(input) {
-          return "Feedback too short" if input.length < 5
-          nil
-        }
-    end
-
-    # Save the survey (your business logic)
-    save_survey(name, rating, feedback, app.msisdn)
-
-    # Thank you message
-    app.say "Thank you #{name}! Your feedback (#{rating}⭐) has been recorded."
-  end
-
-  private
-
-  def save_survey(name, rating, feedback, phone)
-    # Your database logic here
-    Rails.logger.info "Survey: #{name} (#{phone}) rated #{rating}/5: #{feedback}"
-    
-    # Example: Save to database
-    # Survey.create!(
-    #   name: name,
-    #   rating: rating.to_i,
-    #   feedback: feedback,
-    #   phone: phone,
-    #   platform: app.platform
-    # )
-  end
-end
+# config/initializers/flow_chat.rb
+FlowChat::Config.cache = Rails.cache
 ```
 
-### 2. Create Controllers for Each Platform
+Without a cache configured, `FlowChat::Session::CacheSessionStore` raises when it tries to read or write a session.
+
+## Write your first flow
 
-#### USSD Controller
+A flow is a class that inherits `FlowChat::Flow` and reads and writes the conversation through `app`. Each `app.screen` is one step:
 
 ```ruby
-# app/controllers/ussd_controller.rb
-class UssdController < ApplicationController
-  skip_forgery_protection
-  
-  def nalo_webhook
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Ussd::Gateway::Nalo
-      config.use_session_store FlowChat::Session::CacheSessionStore
-      
-      # Optional: Configure USSD-specific settings
-      config.use_session_config(boundaries: [:flow, :platform])
+class RegistrationFlow < FlowChat::Flow
+  def main_page
+    name = app.screen(:name) { |prompt| prompt.ask "What's your name?" }
+
+    email = app.screen(:email) do |prompt|
+      prompt.ask "Your email?", validate: ->(input) { "Invalid email" unless input.include?("@") }
     end
 
-    processor.run SurveyFlow, :start
+    app.say "Welcome #{name}!"
   end
 end
 ```
 
-#### WhatsApp Controller
+FlowChat re-runs this method from the top on every webhook. Each `screen` returns its stored answer when the session already holds one, and re-prompts when it does not, so the method reads as a straight-line script even though each turn is a separate stateless request. For the mechanics, see [How the replay engine works](../README.md#how-the-replay-engine-works).
 
-```ruby
-# app/controllers/whatsapp_controller.rb
-class WhatsappController < ApplicationController
-  skip_forgery_protection
-  
-  def webhook
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
+Put the flow anywhere Rails autoloads it, for example `app/flow_chat/registration_flow.rb`.
 
-    processor.run SurveyFlow, :start
-  rescue => e
-    Rails.logger.error "WhatsApp error: #{e.message}"
-    head :internal_server_error
-  end
-end
-```
+## Wire a controller
 
-#### Telegram Controller
+Build a processor in your webhook action, choose a gateway and session store, and run the flow. Here `self` is the controller:
 
 ```ruby
-# app/controllers/telegram_controller.rb
-class TelegramController < ApplicationController
+# app/controllers/ussd_controller.rb
+class UssdController < ApplicationController
   skip_forgery_protection
 
   def webhook
     processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Telegram::Gateway::BotApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
-
-    processor.run SurveyFlow, :start
-  rescue => e
-    Rails.logger.error { "Telegram error: #{e.message}" }
-    head :internal_server_error
-  end
-end
-```
-
-#### HTTP API Controller
-
-```ruby
-# app/controllers/api/chat_controller.rb
-class Api::ChatController < ApplicationController
-  before_action :authenticate_api_user # Your auth logic
-
-  def message
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Http::Gateway::Simple
+      config.use_gateway FlowChat::Ussd::Gateway::Nalo
       config.use_session_store FlowChat::Session::CacheSessionStore
-
-      # Session isolation per API user
-      config.use_session_config(identifier: :user_id)
     end
 
-    processor.run SurveyFlow, :start
-    # Automatically returns JSON response
+    processor.run RegistrationFlow, :main_page
   end
 end
 ```
 
-### 3. Add Routes
+`skip_forgery_protection` is needed because gateway webhooks are POSTs from an external service that cannot carry a Rails CSRF token. Point a route at the action:
 
 ```ruby
 # config/routes.rb
-Rails.application.routes.draw do
-  # USSD routes
-  post '/ussd/nalo', to: 'ussd#nalo_webhook'
-
-  # WhatsApp routes
-  post '/whatsapp/webhook', to: 'whatsapp#webhook'
-  get '/whatsapp/webhook', to: 'whatsapp#verify' # For webhook verification
-
-  # Telegram routes
-  post '/telegram/webhook', to: 'telegram#webhook'
-
-  # API routes
-  namespace :api do
-    post '/chat/message', to: 'chat#message'
-  end
-end
+post "/ussd", to: "ussd#webhook"
 ```
 
-### 4. Configuration
-
-#### Environment Variables
-
-Add these to your `.env` file:
+To run the same flow on another platform, change only `config.use_gateway`. The gateway classes and their platform symbols are listed in the [README](../README.md#wiring-a-platform).
 
-```bash
-# WhatsApp Configuration
-WHATSAPP_ACCESS_TOKEN=your_access_token
-WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
-WHATSAPP_VERIFY_TOKEN=your_verify_token
-WHATSAPP_APP_SECRET=your_app_secret
-
-# Telegram Configuration
-TELEGRAM_BOT_TOKEN=your_bot_token
-TELEGRAM_SECRET_TOKEN=your_webhook_secret  # Optional: for webhook validation
-```
+## Try it in the simulator
 
-#### FlowChat Configuration
-
-Create `config/initializers/flow_chat.rb`:
-
-```ruby
-FlowChat::Config.logger = Rails.logger
-FlowChat::Config.cache = Rails.cache
-
-# USSD Configuration
-FlowChat::Config.ussd.pagination_page_size = 160  # Adjust for your network
-FlowChat::Config.ussd.pagination_next_option = "#"
-FlowChat::Config.ussd.pagination_back_option = "0"
-
-# WhatsApp Configuration
-FlowChat::Config.whatsapp.message_handling_mode = :inline  # or :background
-```
-
-### 5. Test Your Application
-
-#### Using the Built-in Simulator
-
-Create a simple test in `rails console`:
-
-```ruby
-# Start a simulator session
-simulator = FlowChat::Simulator.new(SurveyFlow, :start)
+FlowChat ships a web simulator for driving flows locally without a real gateway. It requires `FlowChat::Config.simulator_secret` to be set (for example in your initializer). Once set, you can step through a flow from the browser during development. See [testing.md](testing.md) for how to mount and use it.
 
-# Simulate the conversation
-simulator.start
-# => "Welcome to our survey! What's your name?"
-
-simulator.send_message("John Doe")
-# => "Hi John Doe! Rate our service:"
-
-simulator.select_option("5")
-# => "Any additional feedback?"
-
-simulator.send_message("Great service, very helpful!")
-# => "Thank you John Doe! Your feedback (5⭐) has been recorded."
-```
-
-#### Testing HTTP API
-
-```bash
-# Test the HTTP endpoint
-curl -X POST http://localhost:3000/api/chat/message \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer your_api_token" \
-  -d '{
-    "user_id": "user123",
-    "input": "Hello"
-  }'
-```
-
-#### Testing USSD (using simulator)
-
-Visit your Rails app with the simulator enabled:
-
-```ruby
-# In development, add this to your controller
-processor = FlowChat::Processor.new(self, enable_simulator: true) do |config|
-  config.use_gateway FlowChat::Ussd::Gateway::Nalo
-  # ... other config
-end
-```
-
-## Key Concepts
-
-### 1. Screen-Based Navigation
-
-FlowChat uses a **screen-based** approach where each `app.screen(:key)` represents a step in your conversation:
-
-- **Automatic State Management**: Each screen's result is automatically cached
-- **Navigation Stack**: FlowChat tracks where users are in the flow  
-- **Resume Capability**: Users can return to where they left off
-
-### 2. Platform Abstraction
-
-The same flow code works across all platforms because:
-
-- **Unified Prompts**: `prompt.ask()` and `prompt.select()` adapt to each platform
-- **Context Normalization**: All platforms provide consistent context (phone number, input, etc.)
-- **Flexible Rendering**: Emojis show on WhatsApp, get stripped for USSD
-
-### 3. Pluggable Gateways
-
-Each platform can have multiple gateway implementations:
-
-```ruby
-# USSD with different providers
-config.use_gateway FlowChat::Ussd::Gateway::Nalo
-# config.use_gateway FlowChat::Ussd::Gateway::Africaist
-# config.use_gateway YourCompany::Ussd::Gateway::CustomProvider
-
-# WhatsApp with different APIs
-config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-# config.use_gateway FlowChat::Whatsapp::Gateway::OnPremise
-# config.use_gateway YourCompany::Whatsapp::Gateway::Twilio
-```
-
-### 4. Session Management
-
-FlowChat provides flexible session configuration:
-
-```ruby
-# Ephemeral sessions (restart on each request)
-config.use_session_config(identifier: :request_id)
-
-# Durable sessions (persist across timeouts using phone number)
-config.use_durable_sessions
-
-# Cross-platform sessions (same user, different platforms)
-config.use_cross_platform_sessions
-
-# Multi-tenant isolation
-config.use_url_isolation
-```
-
-## Next Steps
-
-Now that you have a basic multi-platform application running:
-
-1. **Explore Platform Features**: Learn platform-specific capabilities
-   - [USSD Development](platforms/ussd.md) - Pagination, choice mapping
-   - [WhatsApp Development](platforms/whatsapp.md) - Rich media, templates
-   - [Telegram Development](platforms/telegram.md) - Inline keyboards, media, callbacks
-   - [HTTP Development](platforms/http.md) - API integration patterns
-
-2. **Advanced Topics**:
-   - [Session Management](../session-management.md) - Deep dive into session boundaries
-   - [Middleware Development](../middleware.md) - Custom processing logic
-   - [Gateway Development](../gateway-development.md) - Build your own platform support
-
-3. **Production Deployment**:
-   - [Configuration](../configuration.md) - Production-ready settings
-   - [Background Jobs](../background-jobs.md) - Async processing for WhatsApp
-   - [Testing](../testing.md) - Comprehensive testing strategies
-
-## Common Patterns
-
-### Validation and Transformation
-
-```ruby
-app.screen(:phone) do |prompt|
-  prompt.ask "Enter your phone number:",
-    validate: ->(input) {
-      return "Invalid phone format" unless input.match?(/^\+?[\d\s-()]+$/)
-      parsed = Phonelib.parse(input)
-      return "Invalid phone number" unless parsed.valid?
-      nil
-    },
-    transform: ->(input) { Phonelib.parse(input).e164 }
-end
-```
-
-### Conditional Flow Logic
-
-```ruby
-def main_menu
-  user_type = determine_user_type(app.msisdn)
-  
-  if user_type == :premium
-    premium_menu
-  else
-    basic_menu
-  end
-end
-```
-
-### Error Handling
-
-```ruby
-def payment_flow
-  begin
-    amount = app.screen(:amount) { |p| p.ask "Enter amount:" }
-    process_payment(amount)
-    app.say "Payment successful!"
-  rescue PaymentError => e
-    app.say "Payment failed: #{e.message}"
-  end
-end
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Session Not Persisting**
-   - Check your session store configuration
-   - Verify session boundaries match your use case
-
-2. **Gateway Errors**
-   - Ensure environment variables are set correctly
-   - Check gateway-specific configuration requirements
-
-3. **Platform Differences**
-   - Test flows on each platform's simulator
-   - Be aware of character limits (USSD) vs rich features (WhatsApp)
-
-### Debug Mode
-
-Enable comprehensive logging:
-
-```ruby
-# config/initializers/flow_chat.rb
-FlowChat::Config.logger.level = Logger::DEBUG
-
-# In your flow
-Rails.logger.debug "Current screen: #{app.navigation_stack.last}"
-Rails.logger.debug "User input: #{app.input.inspect}"
-```
+## Next steps
 
-Ready to build more sophisticated flows? Continue with the [Architecture Overview](architecture.md) to understand FlowChat's design principles. 
+- [configuration.md](configuration.md) for the full config surface and session options.
+- [platforms/ussd.md](platforms/ussd.md), [platforms/whatsapp.md](platforms/whatsapp.md), and [platforms/telegram.md](platforms/telegram.md) for platform-specific behavior.