feat!: inbound media support with FlowChat::Input turn value object

[thedumbtechguy]

Summary

Adds inbound media support so flows can read the media, location, and contact data users send — previously app.media/app.location/app.contact_name were hardcoded to nil, stranding data the WhatsApp/Telegram gateways already parsed. Fills in inbound parsing for Intercom and HTTP, and — as the branch evolved — replaces the old input-sentinel model with a rich FlowChat::Input value object so text and attachments are first-class on every turn.

The turn is now a value object

Every turn is a FlowChat::Input (app.input) with two independent axes: text and an optional attachment.

• app.text → the turn's text (message body or a media caption). Always a String; "" when the turn carried no text (e.g. a caption-less photo).
• app.attachment_type → :media / :location / :contact / nil — the discriminator to branch on.
• app.media → always an Array<FlowChat::Media> (empty when none), so multi-attachment messages never silently drop items.
• app.location, app.contact, app.contact_name.
• FlowChat::Media: type (normalized: :photo→:image, :voice→:audio), raw_type (platform-native), mime_type, caption, filename, id/file_id, plus url/download to fetch bytes per platform.

FlowChat::Input delegates public String methods to its text, so existing validate/transform lambdas (input.strip, input.to_i, input.blank?) keep working unchanged — and they can now also inspect attachments (input.media.any?). A screen is satisfied when input.submitted? — text or an attachment — so a caption-less photo still answers.

Platform coverage

Platform	Inbound media	Notes
WhatsApp	✓	media-id → get_media_url/download_media
Telegram	✓	new client get_file/file_url/download_file; message-level captions captured
Intercom	✓	attachments array (multi-attachment); body captured as caption
HTTP	✓	via media_url/media_type/mime_type params
USSD	—	text-only, out of scope

⚠️ Breaking changes

• The "$media$", "$location$", and "$contact$" input sentinels are removed. context.input is always plain text now ("" when a turn carries no text); the structured payload lives on request.media/request.location/request.contact. Branch on app.attachment_type instead of comparing input to a sentinel string.
• app.input is now a FlowChat::Input, not a raw String (it still behaves like its text for string ops and ==).
• app.media always returns an Array<FlowChat::Media> (empty when none) rather than a single object — iterate uniformly. The interim app.media_items accessor is gone; app.media is the list.

Conveyed to git-cliff via a refactor!: commit with a BREAKING CHANGE: footer.

Test Plan

• Full suite green: 1022 tests, 0 failures, 0 errors
• standardrb clean
• FlowChat::Input unit tests (text coercion, submitted?, attachment_type, media-always-a-list, string delegation, public-only respond_to?, equality, START)
• Unit tests for FlowChat::Media (readers, per-platform url/download dispatch, direct-HTTP download, type normalization)
• Gateway inbound-parsing tests (WhatsApp/Telegram/Intercom/HTTP) updated for text-only input, including multi-attachment and caption cases
• App accessor + media_client wiring tests

Design spec and implementation plan under docs/superpowers/.

🤖 Generated with Claude Code

[thedumbtechguy]

Closing: this work is already on master, so there is nothing left to merge.

It landed via cd3b450 — the commit titled "docs: revamp README and all docs, add GitHub Pages landing page (#3)", which despite its subject touched 11 files under lib/ and carried the implementation with it:

lib/flow_chat/input.rb                          |  86 ++++++   created
lib/flow_chat/media.rb                          | 121 ++++++   created
lib/flow_chat/app.rb                            | 101 ++++
lib/flow_chat/telegram/gateway/bot_api.rb       |  36 ++
lib/flow_chat/telegram/client.rb                |  31 ++
lib/flow_chat/intercom/gateway/intercom_api.rb  |  51 ++
lib/flow_chat/http/gateway/simple.rb            |  15 ++
lib/flow_chat/instrumentation.rb                |  14 ++
lib/flow_chat/prompt.rb                         |  13 +-
lib/flow_chat/whatsapp/gateway/cloud_api.rb     |   9 +-
lib/flow_chat.rb                                |  10 --

git cherry reports these 21 commits as unapplied only because the content arrived under different SHAs, so patch-ids do not match.

Verified rather than assumed. Every file that is purely inbound-media is byte-identical between this branch's tip and master:

lib/flow_chat/input.rb, lib/flow_chat/media.rb, lib/flow_chat.rb, test/unit/input_test.rb, test/unit/media_test.rb, test/integration/media_support_test.rb, test/unit/go_back_test.rb, test/unit/http/gateway/simple_test.rb, and all three plan/spec documents.

On master today: 42 media/input tests pass, and app.media / app.location / app.contact are live on the App API. media.rb there is a superset of what this branch builds — it already carries NORMALIZED_TYPES, raw_type and marshal_dump.

A rebase was attempted and abandoned deliberately. The remaining differences are all places master has moved ahead, so replaying these commits would revert them:

• prompt.rb here raises "Media with more than 3 choices is not supported". That restriction was removed on purpose in 9be0ab3 and again in Add Facebook Messenger and Instagram DM gateways, unify choice resolution, and fix delivery instrumentation #9, because the Messenger and Instagram carousels do carry media alongside choices.
• app.rb here resolves media_client across three platforms; master handles five, including Messenger and Instagram.
• instrumentation.rb, telegram/client.rb and the WhatsApp/Intercom/Telegram gateways have all changed under feat(whatsapp): dispatch webhooks on their field, and handle coexistence #8, Add Facebook Messenger and Instagram DM gateways, unify choice resolution, and fix delivery instrumentation #9 and v0.10.0.

The design document on master already carries a "Superseded (historical)" header noting where the shipped API diverged, which is the accurate record.