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