flow_chat 0.8.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 419f60cf88904f992a2bcf4e93646e68adaee3fcdac5a96d080708b199a2d8a6
-  data.tar.gz: 24ffafb2b588fdaee9775422e8057c073ce133d693dd6e78f19ef32978d40f88
+  metadata.gz: 8cfb138af20136fca40bdc0d7b054e8144ab92e2089c6c446e8c06f5104600f9
+  data.tar.gz: c4ae6902cffe3bcada4c3efe7b72f544fa9ec246570fa72df1b27c977c4f52db
 SHA512:
-  metadata.gz: b49e73727d931e33d9ebff02c0809f31bd3adb7478335be76272961b04db219d98b10664675e32b45998bbcaa9d2d33de3644b84d3d924dc719d797341cd3fe0
-  data.tar.gz: 789fe300b2e3863b88e11a347bf2b205440427b2a70a6cec0d3995bd5a5efc4210dfc66e571412ca79cf642d93ba35890ba6d5270eb1c3b23a727b6beb62f326
+  metadata.gz: f1e719da60370142efbd2b1a44cbb24236e67291340f9015ddd38411b8180cc2f3216d5e56a50464e23a4657d5184ec80ae85225b86e20f1e6673fcc607c1941
+  data.tar.gz: ac3fda919d3fe2bfc939be1454b3e4a4edaf8d4c8d18869244c1492a0bc593d186e0ed5fae626ef035a6905e83433d0197560ceac6bc5bce2a87ffcaa53a3ddd

data/.cliff.toml

@@ -0,0 +1,74 @@
+# git-cliff configuration file
+# https://git-cliff.org/docs/configuration
+
+[changelog]
+# changelog header
+header = """
+# Changelog\n
+All notable changes to this project will be documented in this file.\n
+"""
+# template for the changelog body
+body = """
+{% if version %}\
+    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}\
+    ## [Unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | upper_first }}
+    {% for commit in commits %}
+        - {% if commit.breaking %}[**breaking**] {% endif %}{{ commit.message | upper_first }}\
+    {% endfor %}
+{% endfor %}\n
+"""
+# remove the leading and trailing whitespace from the template
+trim = true
+# changelog footer
+footer = """
+<!-- generated by git-cliff -->
+"""
+
+[git]
+# parse the commits based on https://www.conventionalcommits.org
+conventional_commits = true
+# filter out the commits that are not conventional
+filter_unconventional = true
+# process each line of a commit as an individual commit
+split_commits = false
+# regex for preprocessing the commit messages
+commit_preprocessors = [
+  { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/radioactive-labs/flow_chat/issues/${2}))" },
+]
+# regex for parsing and grouping commits
+commit_parsers = [
+  { message = "^feat", group = "Features" },
+  { message = "^fix", group = "Bug Fixes" },
+  { message = "^doc", group = "Documentation" },
+  { message = "^perf", group = "Performance" },
+  { message = "^refactor", group = "Refactoring" },
+  { message = "^style", group = "Styling" },
+  { message = "^test", group = "Testing" },
+  { message = "^chore\\(release\\): prepare for", skip = true },
+  { message = "^chore", group = "Miscellaneous Tasks" },
+  { body = ".*security", group = "Security" },
+]
+# protect breaking changes from being skipped due to matching a skipping commit_parser
+protect_breaking_commits = false
+# filter out the commits that are not matched by commit parsers
+filter_commits = false
+# glob pattern for matching git tags
+tag_pattern = "v[0-9]*"
+# regex for skipping tags
+skip_tags = ""
+# regex for ignoring tags
+ignore_tags = ""
+# sort the tags topologically
+topo_order = false
+# sort the commits inside sections by oldest/newest order
+sort_commits = "oldest"
+
+[bump]
+# Pre-1.0 semver: a feature bumps the minor, a breaking change also bumps the
+# minor (not the major) while we're on 0.x. Fixes bump the patch.
+features_always_bump_minor = true
+breaking_always_bump_major = false

data/.github/workflows/ci.yml

@@ -39,6 +39,5 @@ jobs:
         ruby-version: '3.2'
         bundler-cache: true
     
-    - name: Run RuboCop
-      run: bundle exec rubocop
-      continue-on-error: true 
+    - name: Run Standard
+      run: bundle exec standardrb 

data/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+# Publishing to RubyGems happens from a laptop (rake release:publish). This
+# workflow only cuts the GitHub Release from the pushed tag — it never pushes to
+# a registry, so it can't race the local publish. workflow_dispatch is kept as a
+# manual escape hatch.
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+
+      - name: Extract version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      # Build the gem only to attach it to the GitHub Release — it is NOT pushed
+      # to RubyGems here (the laptop already did that via rake release:publish).
+      - name: Build gem
+        run: gem build flow_chat.gemspec
+
+      - name: Install git-cliff
+        uses: taiki-e/install-action@v2
+        with:
+          tool: git-cliff
+
+      - name: Generate release notes
+        run: |
+          git-cliff --config .cliff.toml --tag ${{ github.ref_name }} --strip all > RELEASE_NOTES.md
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          body_path: RELEASE_NOTES.md
+          files: |
+            flow_chat-${{ steps.version.outputs.VERSION }}.gem
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/.standard.yml

@@ -0,0 +1,4 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+---
+ruby_version: 3.0

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.9.0] - 2026-07-09
+
+### Features
+
+- Multi-platform gateways, composition architecture, and async processing ([#1](https://github.com/radioactive-labs/flow_chat/issues/1))
+
+### Miscellaneous Tasks
+
+- Add git-cliff changelog and release rake tasks
+- Add security policy and require RubyGems MFA
+
+### Styling
+
+- Adopt StandardRB and format the codebase
+
+## [0.1.0] - 2024-04-04
+
+<!-- generated by git-cliff -->

data/CLAUDE.md

@@ -0,0 +1,327 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Testing
+- `rake test` or `bundle exec rake test` - Run all tests
+- `ruby -Itest test/unit/specific_test.rb` - Run a single test file
+- `ruby -Itest test/unit/specific_test.rb -n test_method_name` - Run a specific test method
+
+### Gem Development
+- `bundle install` - Install dependencies
+- `rake build` - Build the gem
+- `rake release` - Build and release the gem (requires proper credentials)
+
+### Rails Integration Testing
+- Use `rails runner` instead of `rails console` for scripting
+- For production logs, use Rails.logger with block syntax: `Rails.logger.warn { "message" }`
+
+## Architecture Overview
+
+FlowChat is a Rails framework for building conversational interfaces across multiple platforms (USSD, WhatsApp, Telegram, HTTP) using a **composition-based architecture** with **pluggable gateways**.
+
+### Core Components
+
+#### Processor (`lib/flow_chat/processor.rb`)
+- Central orchestrator that builds and executes the middleware stack
+- Configures gateways, session stores, and middleware
+- Entry point: `FlowChat::Processor.new(controller) do |config|`
+
+#### Gateway
+- Platform-specific request/response handling
+- Built-in gateways: `FlowChat::Ussd::Gateway::Nalo`, `FlowChat::Whatsapp::Gateway::CloudApi`, `FlowChat::Telegram::Gateway::BotApi`, `FlowChat::Http::Gateway::Simple`
+- Custom gateways implement: `initialize(app, *args)` and `call(context)`
+
+#### App (`lib/flow_chat/app.rb`)
+- Unified interface for flows to interact with users
+- Key method: `screen(key) { |prompt| ... }` for conversation logic
+- Platform-agnostic accessors: `msisdn`, `user_id`, `platform`, etc.
+
+#### Flow (`lib/flow_chat/flow.rb`)
+- Simple base class containing conversation logic
+- Initialize with `app` instance, implement flow methods
+
+#### Session (`lib/flow_chat/session/`)
+- Configurable session boundaries: `:flow`, `:platform`, `:gateway`, `:url`
+- Session stores: `CacheSessionStore`
+- Session IDs generated based on boundaries and identifiers
+
+#### Factory Pattern (`lib/flow_chat/factory.rb`)
+- Centralized processor configuration system
+- Register configurations once, use everywhere
+- Methods: `register(name, &block)`, `execute(name, controller:)`
+- Eliminates duplication between webhook and background contexts
+- Works seamlessly with `GenericAsyncJob` for async processing
+
+#### Async Background Processing (`lib/flow_chat/async_job.rb`, `gateway_async_support.rb`, `generic_async_job.rb`)
+- Decouple flow processing from webhook request-response cycles
+- Base class: `FlowChat::AsyncJob` for custom background jobs
+- `GenericAsyncJob`: Built-in job that uses Factory pattern (no custom job needed)
+- `BackgroundController` mimics controller interface in background context
+- `GatewayAsyncSupport` concern for gateways to detect and enqueue async jobs
+- Automatic detection: async enqueue, background execute, or inline processing
+- Supported gateways: WhatsApp Cloud API, Intercom API, HTTP Simple (not USSD)
+
+### Middleware Stack Architecture
+
+```
+Gateway -> Session::Middleware -> Custom Middleware -> Executor -> Flow
+```
+
+- **Gateway**: Parses platform-specific requests, renders responses
+- **Session::Middleware**: Manages session boundaries and storage
+- **Custom Middleware**: Business logic, authentication, logging
+- **Executor**: Instantiates flows and handles interrupts
+- **Flow**: Business logic using `app.screen()` for conversation
+
+### Key Patterns
+
+#### Screen-Based Navigation
+```ruby
+def registration_flow
+  email = app.screen(:email) { |p| p.ask "Enter email:", validate: email_validator }
+  name = app.screen(:name) { |p| p.ask "Enter name:", transform: ->(input) { input.titleize } }
+  app.say "Welcome #{name}!"
+end
+```
+
+#### Platform Configuration
+```ruby
+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], identifier: :msisdn)
+end
+```
+
+#### Multi-Platform Support
+Same flow code works across USSD, WhatsApp, Telegram, and HTTP by using platform-agnostic `app.screen()` calls.
+
+#### Factory Pattern with Async
+The recommended approach for async processing using centralized configuration:
+
+```ruby
+# Register factory once in initializer
+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
+
+# Use in webhook controller - one line!
+FlowChat::Factory.execute(:whatsapp, controller: self)
+```
+
+**How it works:**
+1. Webhook calls `Factory.execute(:whatsapp)`
+2. Factory builds processor with `use_async(factory: :whatsapp)`
+3. Gateway enqueues `GenericAsyncJob` with `factory: :whatsapp` param
+4. Background job executes `Factory.execute(:whatsapp)` again
+5. Gateway detects background context and processes inline
+
+**Benefits:**
+- No custom job class needed (`GenericAsyncJob` handles it automatically)
+- Configuration defined once, works in both webhook and background contexts
+- Webhook returns immediately (< 100ms), flow processes in background
+- Automatic prevention of double-enqueueing
+
+See [docs/factory-pattern.md](docs/factory-pattern.md) and [docs/async-background-processing.md](docs/async-background-processing.md) for details.
+
+#### Custom Async Jobs
+For advanced cases, create custom job classes with job params:
+
+```ruby
+class MyFlowJob < FlowChat::AsyncJob
+  def execute(controller, **job_params)
+    deployment_id = job_params[:deployment_id]
+    # ... custom logic with job params
+  end
+end
+
+# Use with job params
+config.use_async(MyFlowJob, deployment_id: 123)
+```
+
+## File Structure
+
+### Core Library (`lib/flow_chat/`)
+- `processor.rb` - Main orchestrator, middleware stack builder
+- `app.rb` - Unified conversation interface
+- `flow.rb` - Base flow class
+- `executor.rb` - Flow execution and interrupt handling
+- `context.rb` - Request context management
+- `config.rb` - Global configuration
+- `factory.rb` - Centralized processor configuration registry
+- `async_job.rb` - Background processing base class and controllers
+- `generic_async_job.rb` - Factory-based async job (no custom class needed)
+- `gateway_async_support.rb` - Async detection and enqueueing concern for gateways
+
+### Platform Gateways
+- `ussd/gateway/nalo.rb` - USSD platform integration (async not supported)
+- `whatsapp/gateway/cloud_api.rb` - WhatsApp Business API integration (async supported)
+- `telegram/gateway/bot_api.rb` - Telegram Bot API integration (async supported)
+- `http/gateway/simple.rb` - HTTP/JSON API integration (async supported)
+- `intercom/gateway/intercom_api.rb` - Intercom customer support integration (async supported)
+- All gateways include `GatewayAsyncSupport` concern for unified async handling
+
+### Session Management (`session/`)
+- `middleware.rb` - Session boundary and ID generation
+- `rails_session_store.rb` - Rails session integration
+- `cache_session_store.rb` - Rails cache integration
+
+### Platform-Specific (`ussd/`, `whatsapp/`, `telegram/`, `http/`, `intercom/`)
+- `renderer.rb` - Platform-specific response formatting
+- `middleware/` - Platform-specific processing logic
+- `intercom/client.rb` - Intercom REST API integration
+- `intercom/configuration.rb` - Intercom credentials and settings
+- `intercom/conversation_manager.rb` - Generic conversation management utilities
+
+### Testing (`test/`)
+- `test_helper.rb` - Test setup with mock Rails environment
+- `unit/` - Unit tests for individual components
+- `integration/` - Integration tests for full flow scenarios
+- `e2e/` - End-to-end tests for platform-specific features
+
+## Testing Approach
+
+- Uses Minitest with custom test helpers
+- Mock Rails environment for testing without full Rails app
+- Test flows using `mock_controller` and session store mocks
+- Platform-specific tests verify gateway behavior
+- Integration tests verify full request/response cycles
+
+## Configuration Patterns
+
+### Global Configuration
+```ruby
+# Logger injection into middleware stack (defaults to true in Rails development)
+FlowChat::Config.inject_middleware_logger = true
+
+# Other global configs
+FlowChat::Config.logger = Rails.logger
+FlowChat::Config.combine_validation_error_with_message = true
+```
+
+### Session Configuration
+```ruby
+config.use_session_config(
+  boundaries: [:flow, :platform],  # Session isolation
+  identifier: :msisdn,              # Session key type  
+  hash_identifiers: true            # Privacy protection
+)
+```
+
+### Multi-Tenancy Support
+```ruby
+config.use_url_isolation  # tenant1.app.com vs tenant2.app.com
+config.use_cross_platform_sessions  # Share sessions between USSD/WhatsApp
+config.use_durable_sessions  # Use user_id instead of request_id
+```
+
+### Intercom Integration
+
+FlowChat provides comprehensive Intercom integration for customer support workflows with proper webhook validation and API client functionality.
+
+#### Configuration
+```ruby
+# Rails credentials (config/credentials.yml.enc)
+intercom:
+  access_token: "your_intercom_access_token"
+  client_secret: "your_intercom_client_secret"
+  skip_signature_validation: false  # Optional: disable webhook validation for testing
+
+# Or environment variables
+INTERCOM_ACCESS_TOKEN=your_intercom_access_token
+INTERCOM_CLIENT_SECRET=your_intercom_client_secret
+INTERCOM_SKIP_SIGNATURE_VALIDATION=false
+```
+
+#### Gateway Setup
+```ruby
+# Basic Intercom gateway setup (default webhook topics)
+config.use_gateway FlowChat::Intercom::Gateway::IntercomApi
+config.use_session_config(boundaries: [:conversation], identifier: :conversation_id)
+
+# With custom configuration
+intercom_config = FlowChat::Intercom::Configuration.get(:my_config)
+config.use_gateway FlowChat::Intercom::Gateway::IntercomApi, intercom_config
+
+# Additional webhook topics (e.g., to include admin events)
+# Note: Default topics (user.created, user.replied) are always included
+config.use_gateway FlowChat::Intercom::Gateway::IntercomApi, nil, [
+  "conversation.admin.assigned",
+  "conversation.admin.replied"
+]
+
+# Custom config AND additional webhook topics
+config.use_gateway FlowChat::Intercom::Gateway::IntercomApi, intercom_config, [
+  "conversation.admin.assigned",
+  "conversation.admin.replied"
+]
+```
+
+**Default Webhook Topics:**
+- `conversation.user.created` - New conversation started by user
+- `conversation.user.replied` - User replied in existing conversation
+
+**Additional Available Topics:**
+- `conversation.admin.assigned` - Admin assigned to conversation
+- `conversation.admin.replied` - Admin replied to conversation
+- `conversation.admin.closed` - Admin closed conversation
+- See [Intercom webhook docs](https://developers.intercom.com/docs/references/webhooks/webhook-models/) for full list
+
+#### Webhook Setup
+1. Add your HTTPS endpoint URL in Intercom Developer Hub → Configure → Webhooks
+2. Intercom validates your endpoint with HEAD request (handled automatically)
+3. Webhook notifications are validated using X-Hub-Signature with client_secret
+
+#### FlowChat Client API
+The FlowChat Intercom client provides only the core methods needed by the gateway:
+
+```ruby
+# Access within a flow via context
+client = context["intercom.client"]
+conversation_id = context["request.conversation_id"]
+
+# Send a message (used by gateway automatically)
+client.send_message(conversation_id, "Hello!", choices: nil, media: nil)
+```
+
+**Note:** Conversations are automatically assigned to the configured admin when messages are sent (Intercom's default behavior). Each admin can change this in their personal settings if desired.
+
+**Important:** For business logic (tags, assignment, state management, fetching conversations), use the official `intercom` gem directly in your application:
+
+```ruby
+# In your application code, use the official gem for business logic
+intercom = Intercom::Client.new(token: access_token)
+
+# Tag management
+intercom.tags.tag(name: "AI_HANDLING", conversations: [{id: conversation_id}])
+
+# Assignment (override default auto-assignment)
+intercom.conversations.reply(id: conversation_id, message_type: "assignment", admin_id: admin_id)
+
+# State management
+intercom.conversations.reply(id: conversation_id, message_type: "closed")
+
+# Fetch conversation details
+conversation = intercom.conversations.find(id: conversation_id)
+```
+
+#### Error Handling
+- Rate limiting: `RateLimitError` with retry-after information
+- Authentication: `ConfigurationError` for invalid tokens
+- API errors: Proper handling for Intercom gem exceptions (ResourceNotFound, AuthenticationError, etc.)
+
+## Instrumentation
+
+FlowChat includes comprehensive instrumentation via `FlowChat::Instrumentation`:
+- Flow execution events
+- Session creation events  
+- Platform-specific metrics
+- Error tracking and logging

data/CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing to Plutonium
+
+## Commit Message Convention
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/) for automated changelog generation and versioning.
+
+### Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+
+- **feat**: A new feature (triggers MINOR version bump)
+- **fix**: A bug fix (triggers PATCH version bump)
+- **docs**: Documentation only changes
+- **style**: Changes that don't affect code meaning (formatting, etc)
+- **refactor**: Code change that neither fixes a bug nor adds a feature
+- **perf**: Performance improvement
+- **test**: Adding or updating tests
+- **chore**: Maintenance tasks (dependencies, tooling, etc)
+
+### Breaking Changes
+
+Add `BREAKING CHANGE:` in the footer or `!` after type to trigger a MAJOR version bump:
+
+```
+feat!: remove deprecated API
+
+BREAKING CHANGE: The old API has been removed. Use new API instead.
+```
+
+### Examples
+
+```bash
+# Feature (bumps 0.26.11 -> 0.27.0)
+git commit -m "feat: add field-level options support for input definitions"
+
+# Bug fix (bumps 0.26.11 -> 0.26.12)
+git commit -m "fix: resolve inheritance issue with controller_for"
+
+# Breaking change (bumps 0.26.11 -> 1.0.0)
+git commit -m "feat!: redesign definition DSL
+
+BREAKING CHANGE: The definition DSL has been completely redesigned.
+See migration guide for details."
+
+# With scope
+git commit -m "feat(ui): add new table component"
+git commit -m "fix(forms): correct hint display on validation errors"
+
+# Documentation
+git commit -m "docs: update definition structure guide"
+```
+
+## Release Process
+
+### Option 1: Automated (Recommended)
+
+```bash
+# See what the next version should be
+rake release:next_version
+
+# Prepare a new release (updates version, generates changelog)
+rake release:prepare[0.27.0]
+
+# Review changes
+git diff
+
+# Full automated release (prepare, commit, tag, push, publish)
+rake release:full[0.27.0]
+```
+
+### Option 2: Manual
+
+```bash
+# 1. Update version in lib/plutonium/version.rb
+# 2. Generate changelog
+git-cliff --tag v0.27.0 -o CHANGELOG.md
+
+# 3. Commit and tag
+git add -A
+git commit -m "chore(release): prepare for v0.27.0"
+git tag v0.27.0
+git push origin main --tags
+
+# 4. GitHub Actions will automatically publish to RubyGems
+```
+
+## Version Bumping Rules
+
+Following semantic versioning:
+
+- **MAJOR** (X.0.0): Breaking changes
+- **MINOR** (0.X.0): New features (backwards compatible)
+- **PATCH** (0.0.X): Bug fixes (backwards compatible)
+
+The automation determines the version bump based on commits since the last tag:
+- Any commit with `BREAKING CHANGE:` or `!` after type → MAJOR
+- Any `feat:` commits → MINOR
+- Any `fix:` commits → PATCH
+
+## Development Setup
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Install git-cliff for changelog generation (optional)
+brew install git-cliff  # macOS
+# or
+cargo install git-cliff  # via Rust
+```
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Make your changes with conventional commits
+4. Run tests: `bundle exec rspec`
+5. Push and create a pull request
+6. The PR title should also follow conventional commit format
+
+## Questions?
+
+Open an issue or discussion on GitHub!

data/Gemfile

@@ -8,3 +8,4 @@ gem "minitest", "~> 5.0"
 gem "minitest-reporters", "~> 1.4"
 gem "ostruct"
 gem "webmock", "~> 3.18"
+gem "standard", "~> 1.3"