@strav/instant 1.0.0-alpha.42

package/src/drivers/telegram/telegram_driver.ts

@@ -0,0 +1,121 @@
+/**
+ * `TelegramDriver` — `InstantDriver` for the Telegram Bot API.
+ *
+ * One bot token, one driver instance. All vendor calls go
+ * through `fetchJson` against `https://api.telegram.org/bot<token>`;
+ * no SDK dependency.
+ *
+ * Telegram has no `reply` endpoint — replies are normal sends
+ * with `reply_parameters.message_id` set. No `multicast` or
+ * `broadcast` either: those are forbidden by Bot API policy
+ * (bots can only message users that started a chat with them).
+ */
+
+import { InstantProviderError } from '../../errors.ts'
+import type { InstantCapability } from '../../instant_capabilities.ts'
+import type { InstantDriver, UserProfile, WebhookOps } from '../../instant_driver.ts'
+import type { OutgoingMessage, SendResult } from '../../message.ts'
+import { fetchJson } from '../../internal/fetch_json.ts'
+import type { WebhookEvent } from '../../webhook_event.ts'
+import type { TelegramProviderConfig } from './telegram_config.ts'
+import { toTelegramCalls } from './telegram_message_mapper.ts'
+import { parseTelegramWebhook, verifyTelegramSignature } from './telegram_webhook.ts'
+
+const DEFAULT_CAPABILITIES: ReadonlySet<InstantCapability> = new Set<InstantCapability>([
+  'send.text',
+  'send.image',
+  'send.video',
+  'send.audio',
+  'send.file',
+  'send.location',
+  'send.sticker',
+  'send.quickReplies',
+  'send.interactive',
+  'push',
+  'profile',
+  'miniApp',
+  'persistentMenu',
+  'webhook.signature',
+  'webhook.parse',
+])
+
+export interface TelegramDriverOptions {
+  instanceName: string
+  config: TelegramProviderConfig
+}
+
+export class TelegramDriver implements InstantDriver {
+  readonly name = 'telegram'
+  readonly instanceName: string
+  readonly capabilities = DEFAULT_CAPABILITIES
+  readonly webhook: WebhookOps
+  private readonly base: string
+
+  constructor(options: TelegramDriverOptions) {
+    const { instanceName, config } = options
+    if (!config.botToken) {
+      throw new InstantProviderError(
+        `TelegramDriver: \`botToken\` is required for provider "${instanceName}".`,
+        { provider: 'telegram', operation: 'init', status: 500 },
+      )
+    }
+    this.instanceName = instanceName
+    const baseURL = config.apiBaseURL ?? 'https://api.telegram.org'
+    this.base = `${baseURL}/bot${config.botToken}`
+    const secret = config.webhookSecretToken
+    this.webhook = {
+      verifySignature: (_rawBody, header) => verifyTelegramSignature(header, secret),
+      parse: (rawBody): WebhookEvent[] => parseTelegramWebhook(rawBody),
+    }
+  }
+
+  async send(to: string, message: OutgoingMessage): Promise<SendResult> {
+    return this.push(to, message)
+  }
+
+  async push(to: string, message: OutgoingMessage): Promise<SendResult> {
+    const calls = toTelegramCalls(to, message)
+    const results: unknown[] = []
+    let lastMessageId: string | undefined
+    for (const call of calls) {
+      const response = await this.invoke<{ result?: { message_id?: number } }>(call.method, call.params)
+      results.push(response)
+      if (response.result?.message_id !== undefined) lastMessageId = String(response.result.message_id)
+    }
+    return {
+      provider: 'telegram',
+      accepted: true,
+      ...(lastMessageId ? { messageId: lastMessageId } : {}),
+      raw: results,
+    }
+  }
+
+  async profile(userId: string): Promise<UserProfile> {
+    const response = await this.invoke<{
+      result: {
+        id: number
+        first_name?: string
+        last_name?: string
+        username?: string
+        photo?: { small_file_id: string }
+      }
+    }>('getChat', { chat_id: userId })
+    const r = response.result
+    const displayName = [r.first_name, r.last_name].filter(Boolean).join(' ') || r.username
+    return {
+      userId: String(r.id),
+      ...(displayName ? { displayName } : {}),
+      raw: r,
+    }
+  }
+
+  private async invoke<T>(method: string, params: Record<string, unknown>): Promise<T> {
+    return fetchJson<T>(`${this.base}/${method}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(params),
+      provider: 'telegram',
+      operation: method,
+    })
+  }
+}

package/src/drivers/telegram/telegram_message_mapper.ts

@@ -0,0 +1,147 @@
+/**
+ * Map `OutgoingMessage` → Telegram Bot-API method + params.
+ *
+ * Telegram has one method per content type (sendMessage,
+ * sendPhoto, sendVideo, …), so the mapper returns a list of
+ * (method, params) tuples — a text + image becomes two calls.
+ * Multiple media attachments collapse into a single
+ * `sendMediaGroup` call.
+ *
+ * Provider-native escape hatches via `raw`:
+ *   - `raw.inlineKeyboard?: InlineKeyboardButton[][]` → `reply_markup.inline_keyboard`
+ *   - `raw.replyToMessageId?: number` → `reply_parameters.message_id`
+ *   - `raw.parseMode?: 'MarkdownV2' | 'HTML'` → `parse_mode`
+ */
+
+import { InstantProviderError } from '../../errors.ts'
+import type { Attachment, OutgoingMessage, QuickReply } from '../../message.ts'
+
+export interface TelegramCall {
+  method: string
+  params: Record<string, unknown>
+}
+
+interface TelegramRawExtras {
+  inlineKeyboard?: unknown[][]
+  replyToMessageId?: number
+  parseMode?: 'MarkdownV2' | 'HTML'
+  disableNotification?: boolean
+}
+
+export function toTelegramCalls(chatId: string, message: OutgoingMessage): TelegramCall[] {
+  const calls: TelegramCall[] = []
+  const raw = (message.raw ?? {}) as TelegramRawExtras
+  const base = baseFields(chatId, raw)
+  const replyMarkup = buildReplyMarkup(message.quickReplies, raw.inlineKeyboard)
+
+  const attachments = message.attachments ?? []
+
+  // Multi-media (≥2 media items) → one sendMediaGroup
+  const mediaGroup = attachments.filter(
+    (a): a is Extract<Attachment, { type: 'image' | 'video' }> =>
+      a.type === 'image' || a.type === 'video',
+  )
+  if (mediaGroup.length >= 2) {
+    const media = mediaGroup.map((a, index) => ({
+      type: a.type === 'image' ? 'photo' : 'video',
+      media: a.url,
+      ...(index === 0 && message.text ? { caption: message.text } : {}),
+    }))
+    calls.push({ method: 'sendMediaGroup', params: { ...base, media } })
+    const leftovers = attachments.filter(
+      (a) => !(mediaGroup as readonly Attachment[]).includes(a),
+    )
+    for (const a of leftovers) calls.push(attachmentCall(a, base))
+    return calls
+  }
+
+  if (attachments.length === 0) {
+    if (!message.text) {
+      throw new InstantProviderError(
+        'Telegram send requires either `text` or at least one attachment.',
+        { provider: 'telegram', operation: 'send', status: 400 },
+      )
+    }
+    calls.push({
+      method: 'sendMessage',
+      params: { ...base, text: message.text, ...(replyMarkup ? { reply_markup: replyMarkup } : {}) },
+    })
+    return calls
+  }
+
+  // Single attachment: caption-eligible types absorb `text`.
+  const [head, ...rest] = attachments
+  if (head) {
+    const captionEligible =
+      head.type === 'image' || head.type === 'video' || head.type === 'audio' || head.type === 'file'
+    const headCall = attachmentCall(head, base)
+    if (captionEligible && message.text) headCall.params['caption'] = message.text
+    if (replyMarkup) headCall.params['reply_markup'] = replyMarkup
+    calls.push(headCall)
+    if (!captionEligible && message.text) {
+      calls.push({ method: 'sendMessage', params: { ...base, text: message.text } })
+    }
+    for (const a of rest) calls.push(attachmentCall(a, base))
+  }
+  return calls
+}
+
+function baseFields(chatId: string, raw: TelegramRawExtras): Record<string, unknown> {
+  return {
+    chat_id: chatId,
+    ...(raw.parseMode ? { parse_mode: raw.parseMode } : {}),
+    ...(raw.disableNotification ? { disable_notification: true } : {}),
+    ...(raw.replyToMessageId
+      ? { reply_parameters: { message_id: raw.replyToMessageId } }
+      : {}),
+  }
+}
+
+function attachmentCall(a: Attachment, base: Record<string, unknown>): TelegramCall {
+  switch (a.type) {
+    case 'image':
+      return { method: 'sendPhoto', params: { ...base, photo: a.url } }
+    case 'video':
+      return { method: 'sendVideo', params: { ...base, video: a.url } }
+    case 'audio':
+      return { method: 'sendAudio', params: { ...base, audio: a.url } }
+    case 'file':
+      return { method: 'sendDocument', params: { ...base, document: a.url } }
+    case 'location':
+      return {
+        method: 'sendLocation',
+        params: { ...base, latitude: a.latitude, longitude: a.longitude },
+      }
+    case 'sticker':
+      // Telegram stickers are addressed by file_id; we forward stickerId verbatim.
+      return { method: 'sendSticker', params: { ...base, sticker: a.stickerId } }
+  }
+}
+
+function buildReplyMarkup(
+  quickReplies: QuickReply[] | undefined,
+  inlineKeyboard: unknown[][] | undefined,
+): Record<string, unknown> | undefined {
+  if (inlineKeyboard) return { inline_keyboard: inlineKeyboard }
+  if (!quickReplies || quickReplies.length === 0) return undefined
+  // Map QuickReply[] → inline_keyboard with one button per row.
+  // `postback` → callback_data; `uri` → url; `message` falls back to text.
+  const inline = quickReplies.map((qr) => {
+    const button: Record<string, unknown> = { text: qr.label }
+    switch (qr.action.type) {
+      case 'postback':
+        button['callback_data'] = qr.action.data
+        break
+      case 'uri':
+        button['url'] = qr.action.uri
+        break
+      case 'message':
+        // No native equivalent — emit as callback_data so the bot
+        // can still respond. App may override via raw.inlineKeyboard.
+        button['callback_data'] = qr.action.text
+        break
+    }
+    return [button]
+  })
+  return { inline_keyboard: inline }
+}

package/src/drivers/telegram/telegram_provider.ts

@@ -0,0 +1,32 @@
+/**
+ * `TelegramInstantProvider` — `ServiceProvider` that registers
+ * the Telegram driver factory on the `InstantManager`.
+ *
+ * Apps list this AFTER `InstantProvider`. Drivers construct
+ * lazily on first `instant.use(name)` call.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { InstantConfigError } from '../../errors.ts'
+import { InstantManager } from '../../instant_manager.ts'
+import type { TelegramProviderConfig } from './telegram_config.ts'
+import { TelegramDriver } from './telegram_driver.ts'
+
+export class TelegramInstantProvider extends ServiceProvider {
+  override readonly name = 'instant-telegram'
+  override readonly dependencies = ['instant']
+
+  override register(app: Application): void {
+    const manager = app.resolve(InstantManager)
+    manager.extend('telegram', ({ instanceName, config }) => {
+      const cfg = config as TelegramProviderConfig
+      if (!cfg.botToken) {
+        throw new InstantConfigError(
+          `TelegramInstantProvider: \`botToken\` is required for provider "${instanceName}".`,
+          { context: { instanceName } },
+        )
+      }
+      return new TelegramDriver({ instanceName, config: cfg })
+    })
+  }
+}

package/src/drivers/telegram/telegram_web_app.ts

@@ -0,0 +1,108 @@
+/**
+ * Telegram Web App helpers — the LIFF analogue for Telegram.
+ *
+ * `verifyTelegramWebAppInitData(initData, botToken)` validates
+ * the `initData` query string a Web App passes from the client
+ * SDK. The signature scheme:
+ *
+ *   secret_key = HMAC_SHA256(bot_token, key="WebAppData")
+ *   expected   = HMAC_SHA256(data_check_string, key=secret_key) (hex)
+ *
+ * `data_check_string` is `key=value` pairs (sorted by key, joined
+ * by `\n`) of every initData field except `hash`.
+ *
+ * Returns the parsed user payload when valid, throws
+ * `InstantProviderError` otherwise.
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { InstantProviderError } from '../../errors.ts'
+
+export interface WebAppUser {
+  id: number
+  first_name?: string
+  last_name?: string
+  username?: string
+  language_code?: string
+}
+
+export interface VerifiedWebAppInitData {
+  user?: WebAppUser
+  auth_date: Date
+  query_id?: string
+  raw: Record<string, string>
+}
+
+export function verifyTelegramWebAppInitData(
+  initData: string,
+  botToken: string,
+  options: { maxAgeSeconds?: number } = {},
+): VerifiedWebAppInitData {
+  const params = new URLSearchParams(initData)
+  const hash = params.get('hash')
+  if (!hash) {
+    throw new InstantProviderError('Telegram Web App initData is missing `hash`.', {
+      provider: 'telegram',
+      operation: 'verifyWebAppInitData',
+      status: 400,
+    })
+  }
+  params.delete('hash')
+  const pairs: string[] = []
+  const all: Record<string, string> = {}
+  for (const [key, value] of [...params.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    pairs.push(`${key}=${value}`)
+    all[key] = value
+  }
+  const dataCheckString = pairs.join('\n')
+  const secretKey = createHmac('sha256', 'WebAppData').update(botToken).digest()
+  const expected = createHmac('sha256', secretKey).update(dataCheckString).digest('hex')
+  if (
+    hash.length !== expected.length ||
+    !timingSafeEqual(Buffer.from(hash, 'hex'), Buffer.from(expected, 'hex'))
+  ) {
+    throw new InstantProviderError('Telegram Web App initData signature does not verify.', {
+      provider: 'telegram',
+      operation: 'verifyWebAppInitData',
+      status: 401,
+    })
+  }
+  const authDateRaw = all['auth_date']
+  if (!authDateRaw) {
+    throw new InstantProviderError('Telegram Web App initData missing `auth_date`.', {
+      provider: 'telegram',
+      operation: 'verifyWebAppInitData',
+      status: 400,
+    })
+  }
+  const authDate = new Date(Number.parseInt(authDateRaw, 10) * 1000)
+  if (options.maxAgeSeconds !== undefined) {
+    const ageSeconds = (Date.now() - authDate.getTime()) / 1000
+    if (ageSeconds > options.maxAgeSeconds) {
+      throw new InstantProviderError('Telegram Web App initData has expired.', {
+        provider: 'telegram',
+        operation: 'verifyWebAppInitData',
+        status: 401,
+      })
+    }
+  }
+  let user: WebAppUser | undefined
+  if (all['user']) {
+    try {
+      user = JSON.parse(all['user']) as WebAppUser
+    } catch {
+      // Leave user undefined when malformed — signature already verified the field.
+    }
+  }
+  return {
+    ...(user ? { user } : {}),
+    auth_date: authDate,
+    ...(all['query_id'] ? { query_id: all['query_id'] } : {}),
+    raw: all,
+  }
+}
+
+/** Build an inline-keyboard button that opens a Telegram Web App. */
+export function webAppButton(text: string, url: string): { text: string; web_app: { url: string } } {
+  return { text, web_app: { url } }
+}

package/src/drivers/telegram/telegram_webhook.ts

@@ -0,0 +1,200 @@
+/**
+ * Telegram webhook signature + parse.
+ *
+ * Signature: Telegram echoes the value of `secret_token` (set on
+ * `setWebhook`) back as the `X-Telegram-Bot-Api-Secret-Token`
+ * header. Constant-time compare against the configured secret.
+ *
+ * Parse: maps `Update` objects to the framework's `WebhookEvent`
+ * union. Anything we don't recognise → `UnknownEvent`.
+ */
+
+import { timingSafeEqual } from 'node:crypto'
+import { WebhookSignatureError } from '../../errors.ts'
+import type {
+  FollowEvent,
+  JoinEvent,
+  LocationMessageEvent,
+  MediaMessageEvent,
+  PostbackEvent,
+  StickerMessageEvent,
+  TextMessageEvent,
+  UnknownEvent,
+  WebhookEvent,
+  WebhookEventBase,
+} from '../../webhook_event.ts'
+
+export function verifyTelegramSignature(
+  header: string | null | undefined,
+  expected: string | undefined,
+): boolean {
+  // When no secret is configured, signature verification is not
+  // available — drivers should refuse to start in that case, but
+  // for safety we return false here too.
+  if (!expected) return false
+  if (!header) return false
+  if (header.length !== expected.length) return false
+  return timingSafeEqual(Buffer.from(header), Buffer.from(expected))
+}
+
+interface TelegramUpdate {
+  update_id: number
+  message?: TelegramMessage
+  edited_message?: TelegramMessage
+  callback_query?: TelegramCallbackQuery
+  my_chat_member?: TelegramChatMemberUpdated
+}
+
+interface TelegramMessage {
+  message_id: number
+  date: number
+  from?: { id: number; language_code?: string }
+  chat: { id: number; type: 'private' | 'group' | 'supergroup' | 'channel' }
+  text?: string
+  caption?: string
+  photo?: Array<{ file_id: string }>
+  video?: { file_id: string }
+  audio?: { file_id: string }
+  voice?: { file_id: string }
+  document?: { file_id: string }
+  sticker?: { file_id: string; set_name?: string }
+  location?: { latitude: number; longitude: number }
+  venue?: { title: string; address: string }
+  new_chat_members?: Array<{ id: number; is_bot: boolean }>
+  left_chat_member?: { id: number; is_bot: boolean }
+}
+
+interface TelegramCallbackQuery {
+  id: string
+  from: { id: number }
+  data?: string
+  message?: TelegramMessage
+}
+
+interface TelegramChatMemberUpdated {
+  chat: { id: number; type: string }
+  from: { id: number }
+  date: number
+  old_chat_member: { status: string; user: { id: number } }
+  new_chat_member: { status: string; user: { id: number; is_bot: boolean } }
+}
+
+export function parseTelegramWebhook(rawBody: string): WebhookEvent[] {
+  let payload: TelegramUpdate
+  try {
+    payload = JSON.parse(rawBody) as TelegramUpdate
+  } catch (cause) {
+    throw new WebhookSignatureError('Telegram webhook body is not valid JSON.', { cause })
+  }
+  const events: WebhookEvent[] = []
+  const event = mapUpdate(payload)
+  if (event) events.push(event)
+  return events
+}
+
+function mapUpdate(u: TelegramUpdate): WebhookEvent | undefined {
+  if (u.message) return mapMessage(u.message)
+  if (u.edited_message) return mapMessage(u.edited_message)
+  if (u.callback_query) return mapCallback(u.callback_query)
+  if (u.my_chat_member) return mapChatMember(u.my_chat_member)
+  return undefined
+}
+
+function baseFromMessage(m: TelegramMessage): WebhookEventBase {
+  return {
+    provider: 'telegram',
+    userId: String(m.from?.id ?? m.chat.id),
+    timestamp: new Date(m.date * 1000),
+    source: m.chat.type === 'private' ? 'user' : m.chat.type === 'channel' ? 'unknown' : 'group',
+    ...(m.chat.type !== 'private' ? { sourceId: String(m.chat.id) } : {}),
+    raw: m,
+  }
+}
+
+function mapMessage(m: TelegramMessage): WebhookEvent {
+  const base = baseFromMessage(m)
+  if (m.text) {
+    const event: TextMessageEvent = { ...base, type: 'message.text', text: m.text, messageId: String(m.message_id) }
+    return event
+  }
+  if (m.photo && m.photo.length > 0) {
+    const event: MediaMessageEvent = { ...base, type: 'message.image', messageId: String(m.message_id) }
+    return event
+  }
+  if (m.video) return { ...base, type: 'message.video', messageId: String(m.message_id) } as MediaMessageEvent
+  if (m.audio || m.voice) return { ...base, type: 'message.audio', messageId: String(m.message_id) } as MediaMessageEvent
+  if (m.document) return { ...base, type: 'message.file', messageId: String(m.message_id) } as MediaMessageEvent
+  if (m.sticker) {
+    const event: StickerMessageEvent = {
+      ...base,
+      type: 'message.sticker',
+      messageId: String(m.message_id),
+      ...(m.sticker.set_name ? { packageId: m.sticker.set_name } : {}),
+      stickerId: m.sticker.file_id,
+    }
+    return event
+  }
+  if (m.location) {
+    const event: LocationMessageEvent = {
+      ...base,
+      type: 'message.location',
+      messageId: String(m.message_id),
+      latitude: m.location.latitude,
+      longitude: m.location.longitude,
+      ...(m.venue?.title ? { title: m.venue.title } : {}),
+      ...(m.venue?.address ? { address: m.venue.address } : {}),
+    }
+    return event
+  }
+  if (m.new_chat_members && m.new_chat_members.some((u) => u.is_bot)) {
+    const event: JoinEvent = { ...base, type: 'join' }
+    return event
+  }
+  if (m.left_chat_member?.is_bot) {
+    const event: JoinEvent = { ...base, type: 'leave' }
+    return event
+  }
+  const fallback: UnknownEvent = { ...base, type: 'unknown' }
+  return fallback
+}
+
+function mapCallback(c: TelegramCallbackQuery): WebhookEvent {
+  const base: WebhookEventBase = {
+    provider: 'telegram',
+    userId: String(c.from.id),
+    timestamp: c.message ? new Date(c.message.date * 1000) : new Date(),
+    source: c.message?.chat.type === 'private' ? 'user' : 'group',
+    ...(c.message && c.message.chat.type !== 'private' ? { sourceId: String(c.message.chat.id) } : {}),
+    replyToken: c.id,
+    raw: c,
+  }
+  const event: PostbackEvent = { ...base, type: 'postback', data: c.data ?? '' }
+  return event
+}
+
+function mapChatMember(u: TelegramChatMemberUpdated): WebhookEvent | undefined {
+  if (!u.new_chat_member.user.is_bot) return undefined
+  const wasMember = u.old_chat_member.status === 'member' || u.old_chat_member.status === 'administrator'
+  const isMember = u.new_chat_member.status === 'member' || u.new_chat_member.status === 'administrator'
+  if (!wasMember && isMember) {
+    const event: FollowEvent = baseFollow(u, 'follow')
+    return event
+  }
+  if (wasMember && !isMember) {
+    const event: FollowEvent = baseFollow(u, 'unfollow')
+    return event
+  }
+  return undefined
+}
+
+function baseFollow(u: TelegramChatMemberUpdated, type: 'follow' | 'unfollow'): FollowEvent {
+  return {
+    provider: 'telegram',
+    userId: String(u.from.id),
+    timestamp: new Date(u.date * 1000),
+    source: u.chat.type === 'private' ? 'user' : 'group',
+    ...(u.chat.type !== 'private' ? { sourceId: String(u.chat.id) } : {}),
+    raw: u,
+    type,
+  }
+}

package/src/drivers/whatsapp/flows/index.ts

@@ -0,0 +1,15 @@
+// Public API of `@strav/instant/whatsapp/flows`.
+
+export {
+  flow,
+  type FlowComponent,
+  type FlowJson,
+  type FlowScreen,
+} from './whatsapp_flow_builder.ts'
+export {
+  decryptFlowRequest,
+  type DecryptedFlowExchange,
+  encryptFlowResponse,
+  type FlowExchangeRequest,
+  type FlowsCryptoOptions,
+} from './whatsapp_flow_crypto.ts'

package/src/drivers/whatsapp/flows/whatsapp_flow_builder.ts

@@ -0,0 +1,55 @@
+/**
+ * Thin typed builder for WhatsApp Flow JSON. Covers the
+ * common shape (version, routing_model, screens with layout +
+ * children); apps that need the full taxonomy hand-write the
+ * JSON and pass it verbatim.
+ */
+
+export interface FlowScreen {
+  id: string
+  title: string
+  terminal?: boolean
+  data?: Record<string, unknown>
+  layout: { type: 'SingleColumnLayout'; children: FlowComponent[] }
+}
+
+export type FlowComponent =
+  | { type: 'TextHeading' | 'TextSubheading' | 'TextBody' | 'TextCaption'; text: string }
+  | { type: 'TextInput'; name: string; label: string; required?: boolean; 'input-type'?: 'text' | 'number' | 'email' | 'phone' }
+  | { type: 'TextArea'; name: string; label: string; required?: boolean }
+  | { type: 'Dropdown' | 'RadioButtonsGroup' | 'CheckboxGroup'; name: string; label: string; 'data-source': Array<{ id: string; title: string }> }
+  | { type: 'Footer'; label: string; 'on-click-action': { name: 'complete' | 'navigate' | 'data_exchange'; payload?: Record<string, unknown>; next?: { type: 'screen'; name: string } } }
+  | { type: 'Image'; src: string; 'scale-type'?: 'cover' | 'contain' }
+
+export interface FlowJson {
+  version: '3.1' | '4.0'
+  data_api_version?: '3.0'
+  routing_model: Record<string, string[]>
+  screens: FlowScreen[]
+}
+
+export function flow(input: {
+  version?: FlowJson['version']
+  dataApiVersion?: FlowJson['data_api_version']
+  screens: FlowScreen[]
+  routing?: Record<string, string[]>
+}): FlowJson {
+  const routing = input.routing ?? deriveRouting(input.screens)
+  return {
+    version: input.version ?? '4.0',
+    ...(input.dataApiVersion ? { data_api_version: input.dataApiVersion } : {}),
+    routing_model: routing,
+    screens: input.screens,
+  }
+}
+
+function deriveRouting(screens: FlowScreen[]): Record<string, string[]> {
+  const map: Record<string, string[]> = {}
+  for (let i = 0; i < screens.length; i++) {
+    const screen = screens[i]
+    if (!screen) continue
+    const next = screens[i + 1]
+    map[screen.id] = next ? [next.id] : []
+  }
+  return map
+}