flow_chat 0.8.2 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 419f60cf88904f992a2bcf4e93646e68adaee3fcdac5a96d080708b199a2d8a6
-  data.tar.gz: 24ffafb2b588fdaee9775422e8057c073ce133d693dd6e78f19ef32978d40f88
+  metadata.gz: a748d7d7a637ca0dc2e0f7c5d8dde213df8fd46eec9117417f141ed6d8aff91d
+  data.tar.gz: ae52d99625691a839cda0e6884ab065bfc5851aa427ceafc4c19ded649c13da7
 SHA512:
-  metadata.gz: b49e73727d931e33d9ebff02c0809f31bd3adb7478335be76272961b04db219d98b10664675e32b45998bbcaa9d2d33de3644b84d3d924dc719d797341cd3fe0
-  data.tar.gz: 789fe300b2e3863b88e11a347bf2b205440427b2a70a6cec0d3995bd5a5efc4210dfc66e571412ca79cf642d93ba35890ba6d5270eb1c3b23a727b6beb62f326
+  metadata.gz: 05e3a2dc63c3c678f0da32f180121caece864af244181f1deb1b668118244e4c342e5656aac7533b79eb3d6f0b3f9f87c62c0ca9faa14243cf9c1ab04c06bea6
+  data.tar.gz: 804ca337d0842bd077f2f2fbde1c864d993ba22d87915e92d869103b8d9adb8ff898cd598dc476bff7625772151be8f49e3853ec93d010cb646e19d9b54e8a06

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/pages.yml

@@ -0,0 +1,43 @@
+name: Deploy landing page to Pages
+
+on:
+  # Runs on pushes to the default branch that touch the site.
+  push:
+    branches: [master]
+    paths:
+      - "site/**"
+      - ".github/workflows/pages.yml"
+
+  # Allows running this workflow manually from the Actions tab.
+  workflow_dispatch:
+
+# Grant GITHUB_TOKEN the permissions required to deploy to GitHub Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel an in-progress production deploy.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+# No build step: the page is a single static file. Upload site/ and deploy it.
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

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,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.10.0] - 2026-08-17
+
+### Bug Fixes
+
+- Correct runtime-breaking session and API misuse
+- Use the full SHA256 for hashed identifiers
+- Use a 128-bit (32-char) hashed identifier
+- Give api.error a contract other than its prose ([#5](https://github.com/radioactive-labs/flow_chat/issues/5))
+
+### Documentation
+
+- [**breaking**] Revamp README and all docs, add GitHub Pages landing page ([#3](https://github.com/radioactive-labs/flow_chat/issues/3))
+- Explain how session boundaries build the session id
+
+### Features
+
+- Map choices on Intercom and HTTP ([#4](https://github.com/radioactive-labs/flow_chat/issues/4))
+- Let a flow declare that it consumed the turn ([#6](https://github.com/radioactive-labs/flow_chat/issues/6))
+- Report a reply the platform would not take ([#7](https://github.com/radioactive-labs/flow_chat/issues/7))
+- Dispatch webhooks on their field, and handle coexistence ([#8](https://github.com/radioactive-labs/flow_chat/issues/8))
+
+### Refactoring
+
+- Fix outdated APIs, dedupe, and harden
+- Drop dead first_message? branch in Intercom flow
+
+## [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