flow_chat 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ebeb5cdcbacce73ec580e381554dbd2377f7896d7d06c488970051f6a8bf599
-  data.tar.gz: bc33f9f54c78264f416e00163e2ba0cf78da2e8e0961c942bb3aab1e86e783e5
+  metadata.gz: 419f60cf88904f992a2bcf4e93646e68adaee3fcdac5a96d080708b199a2d8a6
+  data.tar.gz: 24ffafb2b588fdaee9775422e8057c073ce133d693dd6e78f19ef32978d40f88
 SHA512:
-  metadata.gz: 34006bb23ddaf1aefd8ec4876cb70d8f06d2bbb23da48663ff7a40dd630d9b01af58d9980c343c9d933fa637512375b5c7ba3b0b336ba91a314fdd9ae5fb2ba1
-  data.tar.gz: 78a242f2b175f57ce29326f342c9d4bf4c7c4402c0e2fcd634c21322280dcd0ac273d86eb19750702472218e9d08fd97267ad711b3673f108f89617e5319b9f7
+  metadata.gz: b49e73727d931e33d9ebff02c0809f31bd3adb7478335be76272961b04db219d98b10664675e32b45998bbcaa9d2d33de3644b84d3d924dc719d797341cd3fe0
+  data.tar.gz: 789fe300b2e3863b88e11a347bf2b205440427b2a70a6cec0d3995bd5a5efc4210dfc66e571412ca79cf642d93ba35890ba6d5270eb1c3b23a727b6beb62f326

data/docs/configuration.md

@@ -24,7 +24,7 @@ FlowChat.setup_instrumentation!
 ```ruby
 # Session boundaries control how session IDs are constructed
 FlowChat::Config.session.boundaries = [:flow, :platform]  # default
-FlowChat::Config.session.hash_phone_numbers = true        # hash phone numbers for privacy
+FlowChat::Config.session.hash_identifiers = true          # hash identifiers for privacy
 FlowChat::Config.session.identifier = nil                 # let platforms choose (default)
 
 # Available boundary options:
@@ -193,7 +193,7 @@ processor = FlowChat::Ussd::Processor.new(self) do |config|
   # Configure session boundaries
   config.use_session_config(
     boundaries: [:flow, :platform],     # which boundaries to enforce
-    hash_phone_numbers: true,           # hash phone numbers for privacy
+    hash_identifiers: true,             # hash identifiers for privacy
     identifier: :msisdn                 # use MSISDN for durable sessions (optional)
   )
   

data/docs/http-gateway-protocol.md

@@ -0,0 +1,432 @@
+# FlowChat HTTP Gateway Protocol Specification
+
+**Version:** 1.0  
+**Date:** 2025-06-27  
+**Status:** Stable
+
+## Overview
+
+The FlowChat HTTP Gateway Protocol defines a simple JSON-based request/response format for building conversational flows over HTTP. It enables any HTTP endpoint to participate in FlowChat's conversation framework with session management, media support, and interactive elements.
+
+## Protocol Design
+
+The protocol is designed to be:
+- **Simple**: Easy to implement with any web framework
+- **Stateless**: Each request contains all necessary context
+- **Flexible**: Supports various response types and media
+- **Extensible**: Can be enhanced without breaking compatibility
+
+## Request Format
+
+### HTTP Method
+All requests use **POST** method.
+
+### Headers
+```
+Content-Type: application/json
+Accept: application/json
+```
+
+### Request Body
+```json
+{
+  "session_id": "string",
+  "user_id": "string", 
+  "input": "string",
+  "simulator_mode": boolean
+}
+```
+
+#### Request Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `session_id` | string | Yes | Unique identifier for the conversation session |
+| `user_id` | string | Yes | Unique identifier for the user (phone number, email, etc.) |
+| `input` | string | Yes | User's input message (empty string for initial request) |
+| `simulator_mode` | boolean | No | Indicates if request is from FlowChat simulator |
+
+#### Example Request
+```json
+{
+  "session_id": "sess_abc123",
+  "user_id": "+256700123456",
+  "input": "1",
+  "simulator_mode": true
+}
+```
+
+## Response Format
+
+### HTTP Status Codes
+- **200 OK**: Successful response with flow continuation
+- **400 Bad Request**: Invalid request format
+- **500 Internal Server Error**: Server processing error
+
+### Response Body
+```json
+{
+  "type": "string",
+  "message": "string",
+  "choices": "object|null",
+  "media": "object|null"
+}
+```
+
+#### Response Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | Response type: `prompt`, `text`, or `terminal` |
+| `message` | string | Yes | Text message to display to user |
+| `choices` | object | No | Interactive choices for user selection |
+| `media` | object | No | Media content (images, videos, etc.) |
+
+## Response Types
+
+### 1. Prompt Response
+Interactive response expecting user input with optional choices.
+
+```json
+{
+  "type": "prompt",
+  "message": "Welcome! Please choose an option:",
+  "choices": {
+    "1": "View Profile",
+    "2": "Send Message",
+    "3": "Settings"
+  }
+}
+```
+
+**Behavior**: Session continues, awaiting user input.
+
+### 2. Text Response
+Simple informational message.
+
+```json
+{
+  "type": "text",
+  "message": "Processing your request..."
+}
+```
+
+**Behavior**: Session continues, awaiting user input.
+
+### 3. Terminal Response
+Final message that ends the conversation session.
+
+```json
+{
+  "type": "terminal",
+  "message": "Thank you for using our service. Goodbye!"
+}
+```
+
+**Behavior**: Session ends, no further input expected.
+
+## Choices Format
+
+Choices enable interactive menu-driven flows. They can be provided in two formats:
+
+### Simple Format
+```json
+{
+  "choices": {
+    "1": "Option One",
+    "2": "Option Two",
+    "3": "Option Three"
+  }
+}
+```
+
+### Object Format
+```json
+{
+  "choices": {
+    "choice1": {
+      "key": "1",
+      "value": "Option One"
+    },
+    "choice2": {
+      "key": "2", 
+      "value": "Option Two"
+    }
+  }
+}
+```
+
+**Key Guidelines:**
+- Keys should be simple (numbers, single letters)
+- Values should be descriptive text
+- Maximum 10 choices recommended for usability
+- Empty choices object `{}` means free-form input expected
+
+## Media Support
+
+The protocol supports various media types in responses.
+
+### Image Media
+```json
+{
+  "media": {
+    "type": "image",
+    "url": "https://example.com/image.jpg",
+    "caption": "Optional image caption"
+  }
+}
+```
+
+### Video Media
+```json
+{
+  "media": {
+    "type": "video", 
+    "url": "https://example.com/video.mp4",
+    "caption": "Optional video caption"
+  }
+}
+```
+
+### Document Media
+```json
+{
+  "media": {
+    "type": "document",
+    "url": "https://example.com/document.pdf",
+    "filename": "report.pdf",
+    "caption": "Download the full report"
+  }
+}
+```
+
+### Audio Media
+```json
+{
+  "media": {
+    "type": "audio",
+    "url": "https://example.com/audio.mp3",
+    "caption": "Voice message"
+  }
+}
+```
+
+**Media Guidelines:**
+- URLs must be publicly accessible
+- HTTPS URLs recommended for security
+- Include appropriate file extensions
+- Captions are optional but recommended for accessibility
+
+## Session Management
+
+### Session Lifecycle
+1. **Initialization**: First request has empty `input` field
+2. **Continuation**: Subsequent requests include user input
+3. **Termination**: Response with `type: "terminal"` ends session
+
+### Session State
+The protocol is stateless from HTTP perspective. Session state must be managed by the endpoint implementation using:
+- Database storage
+- In-memory cache
+- External session stores
+- Cookies/tokens (if supported)
+
+### Session ID Format
+- Must be unique across all sessions
+- Recommended: UUID, random string, or timestamped identifier
+- Length: 8-64 characters
+- Characters: alphanumeric, hyphens, underscores
+
+## Error Handling
+
+### Client Errors (4xx)
+```json
+{
+  "type": "terminal",
+  "message": "Invalid request format. Please try again later."
+}
+```
+
+### Server Errors (5xx)
+```json
+{
+  "type": "terminal", 
+  "message": "Service temporarily unavailable. Please try again later."
+}
+```
+
+### Validation Errors
+```json
+{
+  "type": "prompt",
+  "message": "Invalid selection. Please choose from the available options:",
+  "choices": {
+    "1": "Option A",
+    "2": "Option B"
+  }
+}
+```
+
+## Implementation Examples
+
+### Basic Flow Handler
+```ruby
+def handle_http_webhook
+  data = JSON.parse(request.body.read)
+  
+  session_id = data['session_id']
+  user_id = data['user_id']
+  input = data['input']
+  
+  response = case input.downcase.strip
+  when '', 'start'
+    {
+      type: 'prompt',
+      message: 'Welcome! What would you like to do?',
+      choices: {
+        '1' => 'View Account',
+        '2' => 'Make Payment',
+        '3' => 'Get Help'
+      }
+    }
+  when '1'
+    {
+      type: 'text',
+      message: "Account Balance: $150.00\nLast Transaction: -$25.00"
+    }
+  when '2'
+    {
+      type: 'prompt',
+      message: 'Enter payment amount:',
+      choices: {}
+    }
+  when '3'
+    {
+      type: 'terminal',
+      message: 'For help, call 1-800-HELP or visit our website.'
+    }
+  else
+    {
+      type: 'prompt',
+      message: 'Please select a valid option:',
+      choices: {
+        '1' => 'View Account',
+        '2' => 'Make Payment', 
+        '3' => 'Get Help'
+      }
+    }
+  end
+  
+  render json: response
+end
+```
+
+### With Media Support
+```ruby
+def handle_media_flow
+  # ... input parsing ...
+  
+  case input
+  when 'show_chart'
+    {
+      type: 'prompt',
+      message: 'Here is your sales chart:',
+      media: {
+        type: 'image',
+        url: generate_chart_url(user_id),
+        caption: 'Monthly sales data'
+      },
+      choices: {
+        '0' => 'Back to menu'
+      }
+    }
+  end
+end
+```
+
+## Security Considerations
+
+### Input Validation
+- Always validate and sanitize user input
+- Check session_id format and existence
+- Validate user_id against expected format
+- Limit input length to prevent abuse
+
+### Authentication
+- Implement endpoint authentication if needed
+- Validate session ownership
+- Use HTTPS for sensitive data
+- Consider rate limiting
+
+### Data Protection
+- Don't log sensitive user input
+- Encrypt session data if stored
+- Use secure session identifiers
+- Implement proper CORS headers
+
+## Best Practices
+
+### Response Design
+1. **Keep messages concise** - Users prefer short, clear text
+2. **Limit choices** - Maximum 5-7 options for better UX
+3. **Use clear labels** - Make choice text descriptive
+4. **Provide fallbacks** - Handle invalid input gracefully
+5. **End flows properly** - Always provide terminal responses
+
+### Session Management
+1. **Set timeouts** - Expire inactive sessions
+2. **Clean up data** - Remove old session data
+3. **Handle duplicates** - Manage duplicate session IDs
+4. **Log activities** - Track session flow for debugging
+
+### Error Handling
+1. **Fail gracefully** - Provide helpful error messages
+2. **Log errors** - Capture errors for debugging
+3. **Retry logic** - Handle temporary failures
+4. **Fallback flows** - Provide alternative paths
+
+## Protocol Extensions
+
+### Custom Fields
+Implementations may include additional fields in requests/responses:
+
+```json
+{
+  "type": "prompt",
+  "message": "Hello!",
+  "choices": {...},
+  "metadata": {
+    "flow_version": "1.2",
+    "user_lang": "en"
+  }
+}
+```
+
+### Future Enhancements
+- Rich media support (carousels, buttons)
+- Location sharing
+- File uploads
+- Real-time messaging
+- Multi-turn conversations
+
+## Compliance
+
+### HTTP Standards
+- Follows HTTP/1.1 and HTTP/2 specifications
+- Uses standard status codes and headers
+- Supports CORS for cross-origin requests
+
+### JSON Standards
+- Follows RFC 7159 JSON specification
+- Uses UTF-8 encoding
+- Validates JSON schema on input
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0 | 2025-06-27 | Initial specification |
+
+---
+
+For implementation questions or protocol clarifications, please refer to the FlowChat documentation or contact the development team. 

data/docs/sessions.md

@@ -23,7 +23,7 @@ Controls how session IDs are generated and sessions are isolated:
 ```ruby
 # Global session configuration
 FlowChat::Config.session.boundaries = [:flow, :gateway, :platform]  # isolation boundaries
-FlowChat::Config.session.hash_phone_numbers = true                   # privacy protection
+FlowChat::Config.session.hash_identifiers = true                     # privacy protection
 FlowChat::Config.session.identifier = nil                            # platform chooses default
 ```
 
@@ -99,15 +99,15 @@ identifier: :msisdn
 # Same session resumes across conversations
 ```
 
-### Phone Number Hashing
+### Identifier Hashing
 
 When using `:msisdn` identifier, phone numbers are automatically hashed for privacy:
 
 ```ruby
-FlowChat::Config.session.hash_phone_numbers = true  # default
+FlowChat::Config.session.hash_identifiers = true  # default
 # "+256700123456" becomes "a1b2c3d4" (8-character hash)
 
-FlowChat::Config.session.hash_phone_numbers = false
+FlowChat::Config.session.hash_identifiers = false
 # "+256700123456" used directly (not recommended for production)
 ```
 
@@ -135,7 +135,7 @@ processor = FlowChat::Ussd::Processor.new(self) do |config|
   # Explicit session configuration
   config.use_session_config(
     boundaries: [:flow, :platform],     # isolate by flow and platform
-    hash_phone_numbers: true,           # hash phone numbers for privacy
+    hash_identifiers: true,             # hash identifiers for privacy
     identifier: :msisdn                 # use phone number for durable sessions
   )
 end
@@ -352,8 +352,8 @@ end
 ### 5. Security Considerations
 
 ```ruby
-# Always hash phone numbers in production
-FlowChat::Config.session.hash_phone_numbers = true
+# Always hash identifiers in production
+FlowChat::Config.session.hash_identifiers = true
 
 # Use secure cache backends
 config.cache_store = :redis_cache_store, {

data/docs/ussd-setup.md

@@ -147,7 +147,7 @@ Session 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)
-- **`hash_phone_numbers`** - Hash phone numbers for privacy (recommended)
+- **`hash_identifiers`** - Hash identifiers for privacy (recommended)
 
 ## Middleware
 

data/examples/http_controller.rb

@@ -0,0 +1,154 @@
+# Example HTTP Controller for FlowChat HTTP Gateway
+#
+# This controller demonstrates how to use FlowChat with HTTP requests
+# for simple JSON-based conversational interfaces.
+#
+# Usage:
+#   POST /http/webhook
+#   Content-Type: application/json
+#   
+#   {
+#     "session_id": "unique_session_123",
+#     "user_id": "user_456", 
+#     "input": "Hello"
+#   }
+#
+# Response:
+#   {
+#     "type": "prompt",
+#     "session_id": "unique_session_123",
+#     "user_id": "user_456",
+#     "timestamp": "2024-01-01T12:00:00Z",
+#     "message": "Hello! What's your name?",
+#     "choices": [
+#       {"key": "1", "text": "Continue"}
+#     ]
+#   }
+
+class HttpController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    processor = FlowChat::Http::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Http::Gateway::Simple
+      config.use_session_store FlowChat::Session::CacheSessionStore
+      
+      # Configure session management
+      config.use_session_config(
+        boundaries: [:flow, :platform],
+        hash_identifiers: true,
+        identifier: :msisdn  # Use phone number for durable sessions
+      )
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+
+# Example flow for HTTP gateway
+class WelcomeFlow < FlowChat::Flow
+  def main_page
+    name = app.screen(:name) do |prompt|
+      prompt.ask "Hello! What's your name?",
+        validate: ->(input) { "Name is required" if input.blank? },
+        transform: ->(input) { input.strip.titleize }
+    end
+
+    age = app.screen(:age) do |prompt|
+      prompt.ask "Nice to meet you, #{name}! How old are you?",
+        validate: ->(input) { 
+          return "Please enter a number" unless input.match?(/^\d+$/)
+          return "Age must be between 1 and 120" unless (1..120).include?(input.to_i)
+          nil
+        },
+        transform: ->(input) { input.to_i }
+    end
+
+    preferences = app.screen(:preferences) do |prompt|
+      prompt.select "What are you interested in?", {
+        "tech" => "Technology",
+        "sports" => "Sports", 
+        "music" => "Music",
+        "travel" => "Travel"
+      }
+    end
+
+    # Summary
+    app.say "Great! Here's what I learned about you:"
+    app.say "Name: #{name}"
+    app.say "Age: #{age}"
+    app.say "Interest: #{preferences.capitalize}"
+    
+    # Ask if they want to continue
+    continue = app.screen(:continue) do |prompt|
+      prompt.yes? "Would you like to explore more features?"
+    end
+
+    if continue
+      features_demo
+    else
+      app.say "Thanks for trying FlowChat HTTP Gateway! 👋"
+    end
+  end
+
+  private
+
+  def features_demo
+    choice = app.screen(:feature_choice) do |prompt|
+      prompt.select "What would you like to try?", {
+        "media" => "Media Support",
+        "validation" => "Input Validation",
+        "session" => "Session Management"
+      }
+    end
+
+    case choice
+    when "media"
+      media_demo
+    when "validation"
+      validation_demo
+    when "session"
+      session_demo
+    end
+  end
+
+  def media_demo
+    app.say "FlowChat supports rich media in HTTP responses!",
+      media: {
+        url: "https://via.placeholder.com/300x200.png?text=FlowChat+HTTP",
+        type: :image,
+        caption: "FlowChat HTTP Gateway Demo"
+      }
+
+    app.say "Media is returned in the JSON response for your frontend to display."
+  end
+
+  def validation_demo
+    email = app.screen(:email) do |prompt|
+      prompt.ask "Enter your email address:",
+        validate: ->(input) {
+          return "Email is required" if input.blank?
+          return "Invalid email format" unless input.match?(/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
+          nil
+        },
+        transform: ->(input) { input.downcase.strip }
+    end
+
+    app.say "Perfect! Your email #{email} has been validated and normalized."
+  end
+
+  def session_demo
+    # Store some data in session
+    app.session.set("demo_timestamp", Time.current.to_s)
+    app.session.set("demo_counter", (app.session.get("demo_counter") || 0) + 1)
+
+    counter = app.session.get("demo_counter")
+    timestamp = app.session.get("demo_timestamp")
+
+    app.say "Session Demo:"
+    app.say "• This is visit ##{counter} in this session"
+    app.say "• Session started at: #{timestamp}"
+    app.say "• Session data persists across HTTP requests"
+    app.say "• Session ID: #{app.session.context['session.id']}"
+  end
+end