@strav/instant 1.0.0-alpha.42

package/src/drivers/messenger/messenger_driver.ts

@@ -0,0 +1,151 @@
+/**
+ * `MessengerDriver` — `InstantDriver` for Meta's Send API.
+ *
+ * `send`/`push` POST to `/{pageId}/messages` (page-scoped). No
+ * native `multicast`; `broadcast` requires the two-step
+ * Broadcast API (`message_creatives` → `broadcast_messages`)
+ * and only works with a `MESSAGE_TAG` set.
+ *
+ * `profile(userId)` calls `/{userId}?fields=name,profile_pic`
+ * for a Page-scoped PSID.
+ */
+
+import { InstantProviderError, ProviderUnsupportedError } 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 { MetaGraphClient } from '../../internal/meta/meta_graph_client.ts'
+import type { MessengerProviderConfig } from './messenger_config.ts'
+import { toMessengerPayload } from './messenger_message_mapper.ts'
+import { MessengerBotProfile } from './messenger_profile.ts'
+import {
+  parseMessengerWebhook,
+  verifyMessengerChallenge,
+  verifyMessengerSignature,
+} from './messenger_webhook.ts'
+
+const DEFAULT_CAPABILITIES: ReadonlySet<InstantCapability> = new Set<InstantCapability>([
+  'send.text',
+  'send.image',
+  'send.video',
+  'send.audio',
+  'send.file',
+  'send.location',
+  'send.quickReplies',
+  'send.interactive',
+  'send.template',
+  'push',
+  'broadcast',
+  'profile',
+  'persistentMenu',
+  'miniApp',
+  'webhook.signature',
+  'webhook.parse',
+])
+
+export interface MessengerDriverOptions {
+  instanceName: string
+  config: MessengerProviderConfig
+  client?: MetaGraphClient
+}
+
+export class MessengerDriver implements InstantDriver {
+  readonly name = 'messenger'
+  readonly instanceName: string
+  readonly capabilities = DEFAULT_CAPABILITIES
+  readonly webhook: WebhookOps
+  private readonly client: MetaGraphClient
+  private readonly pageId: string
+  private _botProfile?: MessengerBotProfile
+
+  constructor(options: MessengerDriverOptions) {
+    const { instanceName, config } = options
+    for (const field of ['pageId', 'pageAccessToken', 'appSecret', 'verifyToken'] as const) {
+      if (!config[field]) {
+        throw new InstantProviderError(
+          `MessengerDriver: \`${field}\` is required for provider "${instanceName}".`,
+          { provider: 'messenger', operation: 'init', status: 500 },
+        )
+      }
+    }
+    this.instanceName = instanceName
+    this.pageId = config.pageId
+    this.client =
+      options.client ??
+      new MetaGraphClient({
+        accessToken: config.pageAccessToken,
+        ...(config.apiVersion ? { apiVersion: config.apiVersion } : {}),
+        provider: 'messenger',
+      })
+    const appSecret = config.appSecret
+    const verifyToken = config.verifyToken
+    this.webhook = {
+      verifySignature: (rawBody, header) => verifyMessengerSignature(rawBody, header, appSecret),
+      parse: (rawBody) => parseMessengerWebhook(rawBody),
+      verifyChallenge: (params) => verifyMessengerChallenge(params, verifyToken),
+    }
+  }
+
+  async send(to: string, message: OutgoingMessage): Promise<SendResult> {
+    return this.push(to, message)
+  }
+
+  async push(to: string, message: OutgoingMessage): Promise<SendResult> {
+    const body = toMessengerPayload(to, message)
+    const response = await this.client.post<{ message_id?: string; recipient_id?: string }>(
+      `/${this.pageId}/messages`,
+      body,
+      'send',
+    )
+    return {
+      provider: 'messenger',
+      accepted: true,
+      ...(response.message_id ? { messageId: response.message_id } : {}),
+      raw: response,
+    }
+  }
+
+  async broadcast(message: OutgoingMessage): Promise<SendResult> {
+    const raw = (message.raw ?? {}) as { messagingType?: string; tag?: string }
+    if (raw.messagingType !== 'MESSAGE_TAG' || !raw.tag) {
+      throw new ProviderUnsupportedError('messenger', 'broadcast', {
+        reason: 'Broadcast requires `raw.messagingType="MESSAGE_TAG"` and `raw.tag` set to an approved tag.',
+      })
+    }
+    const messageBody = (toMessengerPayload('PLACEHOLDER', message) as { message: unknown }).message
+    const creative = await this.client.post<{ message_creative_id: string }>(
+      '/me/message_creatives',
+      { messages: [messageBody] },
+      'broadcast.creative',
+    )
+    const result = await this.client.post<{ broadcast_id: string }>(
+      '/me/broadcast_messages',
+      { message_creative_id: creative.message_creative_id, messaging_type: 'MESSAGE_TAG', tag: raw.tag },
+      'broadcast.send',
+    )
+    return { provider: 'messenger', accepted: true, messageId: result.broadcast_id, raw: result }
+  }
+
+  async profile(userId: string): Promise<UserProfile> {
+    const response = await this.client.get<{
+      id?: string
+      name?: string
+      first_name?: string
+      last_name?: string
+      profile_pic?: string
+    }>(`/${userId}?fields=name,first_name,last_name,profile_pic`, 'profile')
+    const fullName = [response.first_name, response.last_name].filter(Boolean).join(' ')
+    const displayName = response.name ?? (fullName.length > 0 ? fullName : undefined)
+    return {
+      userId,
+      ...(displayName ? { displayName } : {}),
+      ...(response.profile_pic ? { pictureUrl: response.profile_pic } : {}),
+      raw: response,
+    }
+  }
+
+  get botProfile(): MessengerBotProfile {
+    if (!this._botProfile) this._botProfile = new MessengerBotProfile(this.client)
+    return this._botProfile
+  }
+}

package/src/drivers/messenger/messenger_message_mapper.ts

@@ -0,0 +1,146 @@
+/**
+ * Map `OutgoingMessage` → Messenger Send API body.
+ *
+ * The Send API takes one message per call: `{ recipient, message,
+ * messaging_type }`. Quick replies attach to `message.quick_replies`.
+ * Rich content (generic / button / list / media templates) flows
+ * through `raw.template`.
+ *
+ * Provider-native escape hatches via `raw`:
+ *   - `raw.messagingType?: 'RESPONSE' | 'UPDATE' | 'MESSAGE_TAG'` (default RESPONSE)
+ *   - `raw.tag?: string` — required when messagingType === 'MESSAGE_TAG'
+ *   - `raw.template?: { type: 'generic'|'button'|'list'|'media', payload }`
+ *   - `raw.persona_id?: string`
+ */
+
+import { InstantProviderError } from '../../errors.ts'
+import type { Attachment, OutgoingMessage, QuickReply } from '../../message.ts'
+
+interface MessengerRawExtras {
+  messagingType?: 'RESPONSE' | 'UPDATE' | 'MESSAGE_TAG'
+  tag?: string
+  template?: { type: 'generic' | 'button' | 'list' | 'media'; payload: unknown }
+  persona_id?: string
+  notification_type?: 'REGULAR' | 'SILENT_PUSH' | 'NO_PUSH'
+}
+
+export function toMessengerPayload(to: string, message: OutgoingMessage): Record<string, unknown> {
+  const raw = (message.raw ?? {}) as MessengerRawExtras
+  const messagingType = raw.messagingType ?? 'RESPONSE'
+  if (messagingType === 'MESSAGE_TAG' && !raw.tag) {
+    throw new InstantProviderError(
+      'Messenger MESSAGE_TAG sends require `raw.tag` (the approved message tag).',
+      { provider: 'messenger', operation: 'send', status: 400 },
+    )
+  }
+
+  const body = buildMessage(message, raw)
+
+  return {
+    recipient: { id: to },
+    messaging_type: messagingType,
+    ...(raw.tag ? { tag: raw.tag } : {}),
+    ...(raw.notification_type ? { notification_type: raw.notification_type } : {}),
+    ...(raw.persona_id ? { persona_id: raw.persona_id } : {}),
+    message: body,
+  }
+}
+
+function buildMessage(
+  message: OutgoingMessage,
+  raw: MessengerRawExtras,
+): Record<string, unknown> {
+  const body: Record<string, unknown> = {}
+  const quickReplies = mapQuickReplies(message.quickReplies)
+  if (quickReplies) body['quick_replies'] = quickReplies
+
+  if (raw.template) {
+    body['attachment'] = {
+      type: 'template',
+      payload: { template_type: raw.template.type, ...(raw.template.payload as object) },
+    }
+    if (message.text && !('text' in body)) body['text'] = message.text
+    return body
+  }
+
+  const attachment = message.attachments?.[0]
+  if (attachment) {
+    body['attachment'] = attachmentPayload(attachment)
+    return body
+  }
+
+  if (message.text) {
+    body['text'] = message.text
+    return body
+  }
+
+  if (!quickReplies) {
+    throw new InstantProviderError(
+      'Messenger send requires `text`, an attachment, or `raw.template`.',
+      { provider: 'messenger', operation: 'send', status: 400 },
+    )
+  }
+  return body
+}
+
+function mapQuickReplies(quickReplies: QuickReply[] | undefined): unknown[] | undefined {
+  if (!quickReplies || quickReplies.length === 0) return undefined
+  if (quickReplies.length > 13) {
+    throw new InstantProviderError(
+      'Messenger supports at most 13 quick replies per message.',
+      { provider: 'messenger', operation: 'send', status: 400 },
+    )
+  }
+  return quickReplies.map((qr) => {
+    const base: Record<string, unknown> = { content_type: 'text', title: qr.label.slice(0, 20) }
+    switch (qr.action.type) {
+      case 'postback':
+        base['payload'] = qr.action.data
+        break
+      case 'message':
+        base['payload'] = qr.action.text
+        break
+      case 'uri':
+        // No native URL quick reply — emit as text and let the
+        // bot field it as a payload click.
+        base['payload'] = qr.action.uri
+        break
+    }
+    if (qr.iconUrl) base['image_url'] = qr.iconUrl
+    return base
+  })
+}
+
+function attachmentPayload(a: Attachment): Record<string, unknown> {
+  switch (a.type) {
+    case 'image':
+      return { type: 'image', payload: { url: a.url, is_reusable: false } }
+    case 'video':
+      return { type: 'video', payload: { url: a.url, is_reusable: false } }
+    case 'audio':
+      return { type: 'audio', payload: { url: a.url, is_reusable: false } }
+    case 'file':
+      return { type: 'file', payload: { url: a.url, is_reusable: false } }
+    case 'location':
+      // Messenger doesn't accept outbound location attachments;
+      // surface via a generic template anchor instead.
+      return {
+        type: 'template',
+        payload: {
+          template_type: 'generic',
+          elements: [
+            {
+              title: a.title ?? 'Location',
+              subtitle: a.address,
+              default_action: {
+                type: 'web_url',
+                url: `https://maps.google.com/?q=${a.latitude},${a.longitude}`,
+              },
+            },
+          ],
+        },
+      }
+    case 'sticker':
+      return { type: 'image', payload: { url: a.stickerId, is_reusable: false } }
+  }
+}

package/src/drivers/messenger/messenger_profile.ts

@@ -0,0 +1,43 @@
+/**
+ * Messenger Profile API helpers — sets the bot's get-started
+ * button, persistent menu, and greeting on the Page-scoped
+ * profile. Used by apps onboarding a new bot deployment.
+ *
+ * Exposed via `MessengerDriver.profile()` is the *user* profile
+ * lookup (Page-scoped id → public name). These helpers configure
+ * the *bot's own* profile and are reached via
+ * `driver.botProfile`.
+ */
+
+import type { MetaGraphClient } from '../../internal/meta/meta_graph_client.ts'
+
+export interface PersistentMenuEntry {
+  locale: 'default' | string
+  composer_input_disabled?: boolean
+  call_to_actions: PersistentMenuItem[]
+}
+
+export type PersistentMenuItem =
+  | { type: 'postback'; title: string; payload: string }
+  | { type: 'web_url'; title: string; url: string; webview_height_ratio?: 'compact' | 'tall' | 'full' }
+  | { type: 'nested'; title: string; call_to_actions: PersistentMenuItem[] }
+
+export class MessengerBotProfile {
+  constructor(private readonly client: MetaGraphClient) {}
+
+  setGetStarted(payload: string): Promise<unknown> {
+    return this.client.post('/me/messenger_profile', { get_started: { payload } }, 'setGetStarted')
+  }
+
+  setGreeting(greetings: Array<{ locale: string; text: string }>): Promise<unknown> {
+    return this.client.post('/me/messenger_profile', { greeting: greetings }, 'setGreeting')
+  }
+
+  setPersistentMenu(menu: PersistentMenuEntry[]): Promise<unknown> {
+    return this.client.post('/me/messenger_profile', { persistent_menu: menu }, 'setPersistentMenu')
+  }
+
+  deletePersistentMenu(): Promise<unknown> {
+    return this.client.post('/me/messenger_profile', { fields: ['persistent_menu'] }, 'deletePersistentMenu')
+  }
+}

package/src/drivers/messenger/messenger_provider.ts

@@ -0,0 +1,31 @@
+/**
+ * `MessengerInstantProvider` — `ServiceProvider` that registers
+ * the Messenger Send API driver factory on the `InstantManager`.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { InstantConfigError } from '../../errors.ts'
+import { InstantManager } from '../../instant_manager.ts'
+import type { MessengerProviderConfig } from './messenger_config.ts'
+import { MessengerDriver } from './messenger_driver.ts'
+
+export class MessengerInstantProvider extends ServiceProvider {
+  override readonly name = 'instant-messenger'
+  override readonly dependencies = ['instant']
+
+  override register(app: Application): void {
+    const manager = app.resolve(InstantManager)
+    manager.extend('messenger', ({ instanceName, config }) => {
+      const cfg = config as MessengerProviderConfig
+      for (const field of ['pageId', 'pageAccessToken', 'appSecret', 'verifyToken'] as const) {
+        if (!cfg[field]) {
+          throw new InstantConfigError(
+            `MessengerInstantProvider: \`${field}\` is required for provider "${instanceName}".`,
+            { context: { instanceName, field } },
+          )
+        }
+      }
+      return new MessengerDriver({ instanceName, config: cfg })
+    })
+  }
+}

package/src/drivers/messenger/messenger_webhook.ts

@@ -0,0 +1,165 @@
+/**
+ * Messenger webhook — signature delegates to the shared Meta
+ * verifier; parser walks `entry[].messaging[]`.
+ *
+ * Mapping:
+ *   - `message.text` → `message.text`
+ *   - `message.attachments[].type === 'location'` → `message.location`
+ *   - other `attachments[]` → `message.image|video|audio|file`
+ *   - `message.quick_reply` → `postback` with `data = payload`
+ *   - `postback` → `postback`
+ *   - `referral`, `optin` → `follow` (synthetic — these signal
+ *     a new conversation entry-point)
+ *   - `reaction`, `read`, `delivery`, `account_linking` → `unknown`
+ */
+
+import { WebhookSignatureError } from '../../errors.ts'
+import { verifyMetaChallenge } from '../../internal/meta/meta_webhook_challenge.ts'
+import { verifyMetaSignature } from '../../internal/meta/meta_signature.ts'
+import type {
+  FollowEvent,
+  LocationMessageEvent,
+  MediaMessageEvent,
+  PostbackEvent,
+  TextMessageEvent,
+  UnknownEvent,
+  WebhookEvent,
+  WebhookEventBase,
+} from '../../webhook_event.ts'
+
+export function verifyMessengerSignature(
+  rawBody: string,
+  header: string | null | undefined,
+  appSecret: string,
+): boolean {
+  return verifyMetaSignature(rawBody, header, appSecret)
+}
+
+export function verifyMessengerChallenge(
+  params: Record<string, string | undefined>,
+  verifyToken: string,
+): string | null {
+  return verifyMetaChallenge(params, verifyToken)
+}
+
+interface MessengerPayload {
+  object?: string
+  entry?: MessengerEntry[]
+}
+interface MessengerEntry {
+  id: string
+  time?: number
+  messaging?: MessengerEvent[]
+}
+interface MessengerEvent {
+  sender?: { id: string }
+  recipient?: { id: string }
+  timestamp: number
+  message?: MessengerMessage
+  postback?: { payload: string; title?: string }
+  referral?: { ref?: string; source?: string; type?: string }
+  optin?: { ref?: string }
+  reaction?: unknown
+  read?: unknown
+  delivery?: unknown
+  account_linking?: unknown
+}
+interface MessengerMessage {
+  mid: string
+  text?: string
+  attachments?: Array<{
+    type: 'image' | 'video' | 'audio' | 'file' | 'location' | 'fallback' | 'template'
+    payload: {
+      url?: string
+      coordinates?: { lat: number; long: number }
+      title?: string
+    }
+  }>
+  quick_reply?: { payload: string }
+}
+
+export function parseMessengerWebhook(rawBody: string): WebhookEvent[] {
+  let payload: MessengerPayload
+  try {
+    payload = JSON.parse(rawBody) as MessengerPayload
+  } catch (cause) {
+    throw new WebhookSignatureError('Messenger webhook body is not valid JSON.', { cause })
+  }
+  const events: WebhookEvent[] = []
+  for (const entry of payload.entry ?? []) {
+    for (const m of entry.messaging ?? []) {
+      const event = mapEvent(m)
+      if (event) events.push(event)
+    }
+  }
+  return events
+}
+
+function mapEvent(e: MessengerEvent): WebhookEvent | undefined {
+  if (!e.sender) return undefined
+  const base: WebhookEventBase = {
+    provider: 'messenger',
+    userId: e.sender.id,
+    timestamp: new Date(e.timestamp),
+    source: 'user',
+    raw: e,
+  }
+  if (e.message?.quick_reply) {
+    const event: PostbackEvent = { ...base, type: 'postback', data: e.message.quick_reply.payload }
+    return event
+  }
+  if (e.message?.text) {
+    const event: TextMessageEvent = { ...base, type: 'message.text', text: e.message.text, messageId: e.message.mid }
+    return event
+  }
+  const attachment = e.message?.attachments?.[0]
+  if (attachment) {
+    if (attachment.type === 'location' && attachment.payload.coordinates) {
+      const event: LocationMessageEvent = {
+        ...base,
+        type: 'message.location',
+        messageId: e.message?.mid ?? '',
+        latitude: attachment.payload.coordinates.lat,
+        longitude: attachment.payload.coordinates.long,
+        ...(attachment.payload.title ? { title: attachment.payload.title } : {}),
+      }
+      return event
+    }
+    const mediaType = attachmentToEventType(attachment.type)
+    if (mediaType) {
+      const event: MediaMessageEvent = {
+        ...base,
+        type: mediaType,
+        messageId: e.message?.mid ?? '',
+        ...(attachment.payload.url ? { contentUrl: attachment.payload.url } : {}),
+      }
+      return event
+    }
+  }
+  if (e.postback) {
+    const event: PostbackEvent = { ...base, type: 'postback', data: e.postback.payload }
+    return event
+  }
+  if (e.referral || e.optin) {
+    const event: FollowEvent = { ...base, type: 'follow' }
+    return event
+  }
+  const fallback: UnknownEvent = { ...base, type: 'unknown' }
+  return fallback
+}
+
+function attachmentToEventType(
+  type: string,
+): MediaMessageEvent['type'] | undefined {
+  switch (type) {
+    case 'image':
+      return 'message.image'
+    case 'video':
+      return 'message.video'
+    case 'audio':
+      return 'message.audio'
+    case 'file':
+      return 'message.file'
+  }
+  return undefined
+}

package/src/drivers/telegram/index.ts

@@ -0,0 +1,23 @@
+// Public API of `@strav/instant/telegram`.
+//
+// Subpath barrel for the Telegram driver. Apps register the
+// ServiceProvider in `bootstrap/providers.ts`:
+//
+// ```ts
+// import { InstantProvider } from '@strav/instant'
+// import { TelegramInstantProvider } from '@strav/instant/telegram'
+//
+// export default [InstantProvider, TelegramInstantProvider, ...]
+// ```
+
+export type { TelegramProviderConfig } from './telegram_config.ts'
+export { TelegramDriver, type TelegramDriverOptions } from './telegram_driver.ts'
+export { type TelegramCall, toTelegramCalls } from './telegram_message_mapper.ts'
+export { TelegramInstantProvider } from './telegram_provider.ts'
+export {
+  type VerifiedWebAppInitData,
+  verifyTelegramWebAppInitData,
+  webAppButton,
+  type WebAppUser,
+} from './telegram_web_app.ts'
+export { parseTelegramWebhook, verifyTelegramSignature } from './telegram_webhook.ts'

package/src/drivers/telegram/telegram_config.ts

@@ -0,0 +1,19 @@
+/**
+ * `TelegramProviderConfig` — config shape consumed by
+ * `TelegramInstantProvider`.
+ *
+ * `botToken` is the token from `@BotFather`.
+ * `webhookSecretToken`, when set, is sent back by Telegram as
+ * the `x-telegram-bot-api-secret-token` header on every
+ * webhook POST. Setting it is strongly recommended.
+ */
+
+import type { ProviderConfig } from '../../types.ts'
+
+export interface TelegramProviderConfig extends ProviderConfig {
+  driver: 'telegram'
+  botToken: string
+  webhookSecretToken?: string
+  /** Override Bot API base (defaults to `https://api.telegram.org`). */
+  apiBaseURL?: string
+}