flow_chat 0.8.2 → 0.10.0

data/docs/gateway-context-variables.md

@@ -0,0 +1,168 @@
+# Gateway context variables
+
+Every gateway parses its platform's webhook into a common set of context values. Flows and middleware read these instead of platform-specific request shapes, which is what lets one flow run everywhere. This document lists what each gateway sets.
+
+## All context variables
+
+| Variable | USSD Nalo | HTTP Simple | WhatsApp Cloud API | Messenger Send API | Instagram Send API | Telegram Bot API | Intercom API | Description |
+|----------|-----------|-------------|-------------------|--------------------|--------------------|------------------|--------------|-------------|
+| **Common** |
+| `request.id` | Session id | From user_params | Phone number | PSID | IGSID | Chat id | Conversation id | Session or conversation identifier |
+| `request.user_id` | = msisdn | From user_params | Phone number | PSID | IGSID | Telegram user id | Contact id | Stable per-user identifier |
+| `request.user_name` | none | optional | optional | none | none | First and last name | optional | Sender display name |
+| `request.username` | none | none | none | none | none | Telegram @username | none | Telegram username |
+| `request.msisdn` | set | optional | set | nil | nil | none | optional | E.164 phone number |
+| `request.email` | none | optional | none | none | none | none | optional | User email |
+| `request.message_id` | UUID | UUID | WhatsApp id | `mid` | `mid` | Telegram msg id | optional | Message identifier |
+| `request.timestamp` | Current | Current | Current | Current | Current | From message | Current | ISO8601 timestamp |
+| `request.gateway` | `:nalo` | `:http_simple` | `:whatsapp_cloud_api` | `:messenger_send_api` | `:instagram_send_api` | `:telegram_bot_api` | `:intercom_api` | Gateway symbol |
+| `request.platform` | `:ussd` | `:http` | `:whatsapp` | `:messenger` | `:instagram` | `:telegram` | `:intercom` | Platform symbol |
+| `request.body` | set | set | set | set | set | set | set | Raw request body, string keys |
+| `request.input` | Text | Text | Text (note 1) | Text (note 4) | Text (note 4) | Text (note 2) | Text or nil (note 3) | The turn's text |
+| **Structured attachments** |
+| `request.location` | none | none | set | set | set | set | none | Location payload |
+| `request.media` | none | via `media_url` | set | set | set | set | set (may be several) | Media metadata |
+| `request.contact` | none | none | none | none | none | set | none | Contact payload |
+| **WhatsApp** |
+| `whatsapp.business.phone_number` | | | E.164 business number | | | | | |
+| `whatsapp.business.phone_number_id` | | | WhatsApp phone number id | | | | | |
+| `whatsapp.client` | | | client instance | | | | | |
+| **Messenger** |
+| `messenger.account.id` | | | | Page id | | | | |
+| `messenger.client` | | | | client instance | | | | |
+| **Instagram** |
+| `instagram.account.id` | | | | | Page id or Instagram account id, whichever the webhook named | | | |
+| `instagram.client` | | | | | client instance | | | |
+| **Telegram** |
+| `telegram.client` | | | | | | client instance | | |
+| `telegram.chat_type` | | | | | | private, group, supergroup, channel | | |
+| `telegram.callback_query_id` | | | | | | on callbacks | | |
+| `telegram.original_message_id` | | | | | | on callbacks | | |
+| **HTTP** |
+| `http.method` | | GET or POST | | | | | | |
+| `http.path` | | Request path | | | | | | |
+| `http.user_agent` | | User agent header | | | | | | |
+| **Intercom** |
+| `intercom.client` | | | | | | | client instance | |
+| `intercom.topic` | | | | | | | Webhook event type | |
+
+Notes on `request.input`:
+
+1. WhatsApp: the message text, a media caption, or a button/list reply id. `""` for a structured turn (location, media, contact) that carries no text.
+2. Telegram: the message text, callback data, or a media caption. `""` for a structured turn with no text.
+3. Intercom: the message text or body, or `""`/`nil` for turns without text.
+4. Messenger and Instagram: the message text, a media caption, a quick-reply payload, or a postback payload. `""` for a turn with no text.
+
+`request.msisdn` is `nil` on both Messenger and Instagram: neither platform exposes a phone number, only a PSID or IGSID scoped to the app and the connected account. Use `request.user_id` (or `app.user_id`) as the durable per-user identifier; sessions key on it by default for both platforms.
+
+5. Messenger and Instagram set `request.location`, not `request.media`, for a shared location: the gateway inspects the attachment's `type` and routes a `location` attachment to `request.location` with latitude, longitude, and name, the same as WhatsApp and Telegram. Every other attachment type still sets `request.media`.
+
+`context.input` is always plain text. There are no `"$media$"`/`"$location$"`/`"$contact$"` sentinel values: a structured turn with no text sets `input` to `""` and carries its payload on `request.media`, `request.location`, or `request.contact`. In flows, read `app.input` (a `FlowChat::Input`) or its accessors, described below.
+
+## Reading the turn in a flow
+
+Prefer the accessors on `app` over reading context keys directly. Every turn is a `FlowChat::Input` value object with two independent axes: text and an optional attachment. Text and media can arrive together (a captioned photo); location and contact arrive on their own.
+
+```ruby
+class MyFlow < FlowChat::Flow
+  def start
+    # Identity and platform, available on every platform.
+    user_id  = app.user_id
+    platform = app.platform
+    msisdn   = app.msisdn
+
+    # The turn's text. Always a string, "" when the turn carried no text.
+    message = app.text
+
+    # Branch on the attachment kind, not on a magic input value.
+    case app.attachment_type
+    when :media
+      app.media.each do |item|   # always a list; iterate so you never drop extra attachments
+        item.type       # canonical: :image, :video, :audio, :document, :sticker
+        item.raw_type   # platform-native: :photo or :voice on Telegram
+        item.mime_type
+        item.filename
+        link  = item.url        # a fetchable URL, or nil
+        bytes = item.download   # the raw file bytes, or nil
+      end
+    when :location
+      lat = app.location[:latitude]
+      lng = app.location[:longitude]
+    when :contact
+      name = app.contact[:name]
+    end
+  end
+end
+```
+
+Accessors, all shortcuts to the `app.input` value object:
+
+- `app.text`: the turn's text, or the caption sent with an attachment. Always a string, `""` when there is no text.
+- `app.attachment_type`: `:media`, `:location`, `:contact`, or `nil`, the discriminator to branch on.
+- `app.attachment`: the payload of `attachment_type` (the media list, the location hash, the contact hash, or `nil`).
+- `app.media`: always an `Array<FlowChat::Media>` (empty when none), a list even on single-media platforms, so you iterate uniformly.
+- `app.location`: the location hash, or `nil`.
+- `app.contact`: the shared contact card hash, or `nil`.
+- `app.contact_name`: the sender's display name (distinct from a shared contact card).
+
+## Media
+
+WhatsApp, Messenger, Instagram, Telegram, Intercom, and HTTP set `request.media` for inbound media (USSD is text-only and never sets it). WhatsApp, Messenger, Instagram, and Telegram carry a single item; Intercom may carry several, one per attachment. HTTP callers submit inbound media through the `media_url` request param, with optional `media_type` and `mime_type`.
+
+A `FlowChat::Media` item's `type` is a normalized value; `raw_type` is the platform-native value. The normalization maps `:photo` to `:image` and `:voice` to `:audio`, so `type` is one of `:image`, `:video`, `:audio`, `:document`, `:sticker`.
+
+| Media type | WhatsApp | Messenger / Instagram | Telegram | Fields |
+|------------|----------|------------------------|----------|--------|
+| `:image` (Telegram `:photo`) | yes | yes | yes | id or file_id, mime_type, width, height |
+| `:video` | yes | yes | yes | id or file_id, mime_type, duration, width, height |
+| `:audio` | yes | yes | yes | id or file_id, mime_type, duration, title, performer |
+| `:voice` | no | no | yes | file_id, mime_type, duration |
+| `:document` (Messenger/Instagram `file`) | yes | yes | yes | id or file_id, mime_type, filename |
+| `:sticker` | yes | not confirmed | yes | id or file_id, emoji, set_name, is_animated |
+
+Messenger and Instagram attachments carry only `type` and `url`; there is no separate mime_type, filename, width, height, or duration, because the gateway does not call a lookup API the way WhatsApp does for a media id. `item.url` resolves a fetchable URL per platform (WhatsApp `get_media_url`, Telegram `getFile`, Messenger/Instagram/Intercom/HTTP use the direct URL already on the attachment). `item.download` returns the raw bytes.
+
+Meta routes a shared location to `request.location`, not `request.media`, the same as WhatsApp and Telegram - a location share is not a `FlowChat::Media` item on any of these platforms.
+
+### Inspecting attachments in validate and transform
+
+The `FlowChat::Input` object behaves like its text for string operations, so validators and transforms read naturally, and it also exposes the attachment:
+
+```ruby
+app.screen(:photo) do |prompt|
+  prompt.ask "Send your ID photo",
+    validate: ->(input) { "Please attach a photo" unless input.media.any? }
+end
+
+app.screen(:name) do |prompt|
+  prompt.ask "Your name?", transform: ->(input) { input.strip.titleize }
+end
+```
+
+A turn counts as answered (`input.submitted?`) when it has text or an attachment, so a caption-less photo still satisfies a screen.
+
+### What a screen should return
+
+`prompt.ask` and `prompt.select` return a string (the text, or your `transform`'s result), and that string is what gets stored as the screen's answer. Return those from screen blocks.
+
+`prompt.user_input` is the raw `FlowChat::Input` object, useful inside a `validate` or `transform` when you want the attachment, but avoid returning it as a screen's value:
+
+```ruby
+# Good: persists a string.
+name = app.screen(:name) { |prompt| prompt.ask "Your name?" }
+
+# Avoid: persists the whole Input object into the session store.
+raw = app.screen(:raw) { |prompt| prompt.user_input }
+```
+
+Whatever a screen returns is stored in the session and serialized by the store (`CacheSessionStore` uses `Marshal`). A `FlowChat::Media` serializes without its live platform client, so a media object deserialized from the session has no client and its `url` and `download` return `nil` rather than raising. Fetch media during the turn it arrives, while the client is present; do not rely on downloading it from a stored answer on a later turn.
+
+### Lower-level access
+
+The raw request hashes remain available if you need them, but prefer the accessors above:
+
+```ruby
+app.context["request.media"]     # raw Hash, or Array for Intercom
+app.context["request.location"]
+app.context["request.contact"]
+```

data/docs/gateway-development.md

@@ -0,0 +1,159 @@
+# Building a gateway
+
+A gateway adapts one messaging platform to FlowChat. It is the first and last layer of the middleware stack: it parses the platform's inbound webhook into normalized context values on the way in, and renders the flow's output back to the platform on the way out. FlowChat ships gateways for USSD (Nalo), WhatsApp, Telegram, HTTP, and Intercom; write your own to support anything else.
+
+## The contract
+
+A gateway is a middleware object. It takes the next app in its constructor and implements `call(context)`:
+
+```ruby
+module MyCompany
+  module Sms
+    module Gateway
+      class Twilio
+        def initialize(app, config = nil)
+          @app = app
+          @config = config
+        end
+
+        def call(context)
+          @context = context
+          controller = context.controller
+          params = controller.request.params
+
+          # 1. Parse the inbound webhook into normalized context values.
+          context["request.id"] = params["MessageSid"]
+          context["request.msisdn"] = FlowChat::PhoneNumberUtil.to_e164(params["From"])
+          context["request.user_id"] = context["request.msisdn"]
+          context["request.message_id"] = SecureRandom.uuid
+          context["request.timestamp"] = Time.current.iso8601
+          context["request.gateway"] = :twilio
+          context["request.platform"] = :sms
+          context["request.body"] = params.to_h.transform_keys(&:to_s)
+          context.input = params["Body"].presence || ""
+
+          # 2. Run the rest of the stack. It returns [type, prompt, choices, media].
+          type, prompt, choices, _media = @app.call(context)
+
+          # 3. Render the result back to the platform.
+          message = render(prompt, choices)
+          send_sms(message, to: context["request.msisdn"])
+        end
+
+        private
+
+        def render(prompt, choices)
+          # Turn prompt + choices into whatever the platform expects.
+        end
+
+        def send_sms(message, to:)
+          # Call the platform API.
+        end
+      end
+    end
+  end
+end
+```
+
+`@app.call(context)` returns a four-element array: `[type, prompt, choices, media]`. `type` is `:prompt` while the conversation continues and `:terminal` when it has ended. `prompt` is the message text, `choices` is a hash of choice keys to labels (or `nil`), and `media` is an outbound media hash (or `nil`).
+
+Use the gateway with `use_gateway`, passing any constructor arguments after the class:
+
+```ruby
+processor = FlowChat::Processor.new(self) do |config|
+  config.use_gateway MyCompany::Sms::Gateway::Twilio, sms_config
+  config.use_session_store FlowChat::Session::CacheSessionStore
+end
+```
+
+## Context values to set
+
+The session middleware and `FlowChat::App` read normalized keys off the context. Set the ones your platform can provide:
+
+| Key | Purpose |
+|---|---|
+| `request.id` | The platform's session or conversation id. |
+| `request.user_id` | A stable per-user id (used by `use_durable_sessions`). |
+| `request.msisdn` | The user's phone number in E.164, when available. |
+| `request.message_id` | A unique id for this message. |
+| `request.timestamp` | ISO8601 time of the message. |
+| `request.gateway` | Your gateway's symbol, for example `:twilio`. |
+| `request.platform` | The platform symbol, for example `:sms`. |
+| `request.body` | The raw request payload, with string keys. |
+| `context.input` | The turn's text (a caption or `""` when the turn carries only an attachment). |
+| `request.media` / `request.location` / `request.contact` | Structured attachments, when present. |
+
+The full list and how each existing gateway populates it is in [gateway-context-variables.md](gateway-context-variables.md).
+
+## Adding platform middleware
+
+If your platform needs its own middleware (USSD adds pagination and choice-number mapping), define `self.configure_middleware_stack(builder, custom_middleware)`. The processor calls it in place of the default custom-middleware step, so you decide where your middleware and the user's sit:
+
+```ruby
+def self.configure_middleware_stack(builder, custom_middleware)
+  builder.use MyCompany::Sms::Middleware::Segmentation
+  builder.use custom_middleware
+end
+```
+
+`custom_middleware` is the app's own custom-middleware builder. Include it, or the middleware a user added with `use_middleware` will not run.
+
+## Writing a choice mapper
+
+A choice mapper turns what the platform sends back into the key the flow branches on. Get one rule right and the rest follows:
+
+> **Decide ambiguity under the same equivalence your resolver matches on.**
+
+Every choice bug FlowChat has had came from breaking it — the resolver normalised input one way, and nothing checked whether two choices became indistinguishable under that normalisation, so one of them silently became unreachable.
+
+`FlowChat::ChoiceTitles` enforces the rule for you. Pass it the `fold` your resolver applies and the `measure` your platform sizes fields in, and it hands back titles that are guaranteed distinct — numbering the whole set when they otherwise would not be:
+
+```ruby
+FlowChat::ChoiceTitles.build(choices, title_cap, measure: :characters)
+# => [[key, original_label, displayed_title, was_truncated], ...]
+```
+
+Then make the displayed title the value you put on the wire. It is already unique within the set, so it needs no separate id space to be unique in — a tap sends it back as the payload, and a user who types what they read sends the same string, so one map resolves both.
+
+**The best fold is no fold, and today no mapper uses one:**
+
+| Mapper | Resolves on | Measure |
+|---|---|---|
+| WhatsApp, Messenger, Instagram | the displayed title, matched exactly | characters |
+| Telegram | the displayed title, cut to `callback_data`'s limit | **bytes** |
+| HTTP | the displayed title, matched exactly | characters |
+| USSD, Intercom | the position printed beside each option | — |
+
+USSD and Intercom are the strongest form of the rule: positions are unique whatever the labels say, so their equivalence relation is already injective and there is nothing to check. If your platform prints a number and asks for one, do that and you need none of this. Intercom used to match labels case-insensitively as well, and that is exactly what made two options reading the same collapse onto one entry — the number beside them was already doing that job unambiguously.
+
+The rest match exactly, because a tapped payload and a client-echoed string are both produced by machines rather than typed. Every transform that could absorb a drift in those strings can also merge two choices, so none is worth adding on speculation. If you do add one — a platform where a person types freely might justify case folding — pass it as `fold:` so the ambiguity check uses it too, and expect more sets to be numbered as a result.
+
+Where the number is already on screen — Intercom's numbered list, or the Meta `:numbered` rung — the mapper does not prefix anything, because the renderer is doing it. Prefixing in both places reads as `1. 1. Savings`.
+
+Number the set rather than disambiguating with a suffix. A position prefix sits at the front and survives truncation from the right, which is what makes it work even on a platform as tight as Telegram's 64 bytes; a suffix is the first thing a cut removes.
+
+## Supporting async
+
+Include `FlowChat::GatewayAsyncSupport` to let the gateway run flows in a background job. The concern provides `should_enqueue_async?` (true when async is enabled, the gateway supports it, and the request is not already running in the background) and `enqueue_async_job` (serializes the request and enqueues the job). Override `async_supported?` to return `false` on a synchronous protocol:
+
+```ruby
+class Twilio
+  include FlowChat::GatewayAsyncSupport
+
+  def call(context)
+    @context = context
+    @controller = context.controller
+    return if enqueue_async_job   # enqueued; respond immediately
+
+    # ... otherwise process inline as above
+  end
+end
+```
+
+`enqueue_async_job` returns `false` when async should not be used (for example when the request is already the background job), so you fall through to inline processing. See [async-background-processing.md](async-background-processing.md).
+
+## Related
+
+- [Architecture](architecture.md)
+- [Gateway context variables](gateway-context-variables.md)
+- [Async and background processing](async-background-processing.md)

data/docs/getting-started.md

@@ -0,0 +1,90 @@
+# Getting Started
+
+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
+
+- A Rails application.
+- Ruby 3.0 or newer.
+- A cache the session store can use, such as `Rails.cache`.
+
+## Install
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "flow_chat"
+```
+
+Then run `bundle install`. There are no migrations and no generators to run.
+
+## Configure the cache
+
+The cache-backed session store needs a cache. Set it once during boot, for example in an initializer:
+
+```ruby
+# config/initializers/flow_chat.rb
+FlowChat::Config.cache = Rails.cache
+```
+
+Without a cache configured, `FlowChat::Session::CacheSessionStore` raises when it tries to read or write a session.
+
+## Write your first flow
+
+A flow is a class that inherits `FlowChat::Flow` and reads and writes the conversation through `app`. Each `app.screen` is one step:
+
+```ruby
+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
+
+    app.say "Welcome #{name}!"
+  end
+end
+```
+
+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).
+
+Put the flow anywhere Rails autoloads it, for example `app/flow_chat/registration_flow.rb`.
+
+## Wire a 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/ussd_controller.rb
+class UssdController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    processor = FlowChat::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Ussd::Gateway::Nalo
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run RegistrationFlow, :main_page
+  end
+end
+```
+
+`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
+post "/ussd", to: "ussd#webhook"
+```
+
+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).
+
+## Try it in the simulator
+
+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.
+
+## Next steps
+
+- [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.