@strav/instant 1.0.0-alpha.42

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

@@ -0,0 +1,81 @@
+/**
+ * WhatsApp Flows data-exchange crypto.
+ *
+ * On every data-exchange request, Meta posts:
+ *   { encrypted_flow_data, encrypted_aes_key, initial_vector }
+ * all base64. The server:
+ *   1. Decrypts `encrypted_aes_key` with its RSA-OAEP-SHA256
+ *      private key → 16-byte AES key.
+ *   2. AES-128-GCM decrypts `encrypted_flow_data` with the AES
+ *      key and the provided IV; the last 16 bytes of ciphertext
+ *      are the GCM tag.
+ *   3. Re-encrypts the response with the same AES key, but the
+ *      IV bytewise-flipped (`b ^ 0xff`).
+ *
+ * This module exposes the two operations as pure functions —
+ * the driver layer wires them into a route.
+ */
+
+import { createDecipheriv, createCipheriv, createPrivateKey, privateDecrypt, constants } from 'node:crypto'
+
+export interface FlowExchangeRequest {
+  encrypted_flow_data: string
+  encrypted_aes_key: string
+  initial_vector: string
+}
+
+export interface DecryptedFlowExchange {
+  /** Decrypted JSON payload Meta posted. */
+  payload: Record<string, unknown>
+  /** AES key + IV for encrypting the response — pass to `encryptFlowResponse`. */
+  aesKey: Buffer
+  iv: Buffer
+}
+
+export interface FlowsCryptoOptions {
+  privateKeyPem: string
+  passphrase?: string
+}
+
+export function decryptFlowRequest(
+  body: FlowExchangeRequest,
+  options: FlowsCryptoOptions,
+): DecryptedFlowExchange {
+  const privateKey = createPrivateKey({
+    key: options.privateKeyPem,
+    ...(options.passphrase ? { passphrase: options.passphrase } : {}),
+  })
+  const aesKey = privateDecrypt(
+    {
+      key: privateKey,
+      padding: constants.RSA_PKCS1_OAEP_PADDING,
+      oaepHash: 'sha256',
+    },
+    Buffer.from(body.encrypted_aes_key, 'base64'),
+  )
+  const iv = Buffer.from(body.initial_vector, 'base64')
+  const cipherText = Buffer.from(body.encrypted_flow_data, 'base64')
+  const tagLength = 16
+  const encrypted = cipherText.subarray(0, cipherText.length - tagLength)
+  const tag = cipherText.subarray(cipherText.length - tagLength)
+  const decipher = createDecipheriv('aes-128-gcm', aesKey, iv)
+  decipher.setAuthTag(tag)
+  const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()])
+  const payload = JSON.parse(decrypted.toString('utf8')) as Record<string, unknown>
+  return { payload, aesKey, iv }
+}
+
+export function encryptFlowResponse(
+  response: Record<string, unknown>,
+  aesKey: Buffer,
+  iv: Buffer,
+): string {
+  const flippedIv = Buffer.from(iv.map((b) => b ^ 0xff))
+  const cipher = createCipheriv('aes-128-gcm', aesKey, flippedIv)
+  const encrypted = Buffer.concat([
+    cipher.update(JSON.stringify(response), 'utf8'),
+    cipher.final(),
+  ])
+  const tag = cipher.getAuthTag()
+  return Buffer.concat([encrypted, tag]).toString('base64')
+}

package/src/drivers/whatsapp/index.ts

@@ -0,0 +1,14 @@
+// Public API of `@strav/instant/whatsapp`.
+
+export type {
+  WhatsAppFlowsConfig,
+  WhatsAppProviderConfig,
+} from './whatsapp_config.ts'
+export { WhatsAppDriver, type WhatsAppDriverOptions } from './whatsapp_driver.ts'
+export { toWhatsAppPayload } from './whatsapp_message_mapper.ts'
+export { WhatsAppInstantProvider } from './whatsapp_provider.ts'
+export {
+  parseWhatsAppWebhook,
+  verifyWhatsAppChallenge,
+  verifyWhatsAppSignature,
+} from './whatsapp_webhook.ts'

package/src/drivers/whatsapp/whatsapp_config.ts

@@ -0,0 +1,35 @@
+/**
+ * `WhatsAppProviderConfig` — config shape consumed by
+ * `WhatsAppInstantProvider`.
+ *
+ * `phoneNumberId` is the WABA-issued numeric id (not the E.164
+ * number). `accessToken` is the long-lived system-user token.
+ * `appSecret` is used to verify Meta's X-Hub signature.
+ * `verifyToken` is the value Meta sends as `hub.verify_token`
+ * on the GET-verify handshake.
+ *
+ * `flows` is required only when the app uses WhatsApp Flows for
+ * data-exchange endpoints — Meta encrypts the body with an
+ * ECC-derived AES key, and the driver needs the private key to
+ * decrypt and re-sign responses.
+ */
+
+import type { ProviderConfig } from '../../types.ts'
+
+export interface WhatsAppFlowsConfig {
+  /** Passphrase protecting `privateKeyPem`, if any. */
+  passphrase?: string
+  /** PEM-encoded RSA-2048 / EC private key registered with Meta. */
+  privateKeyPem: string
+}
+
+export interface WhatsAppProviderConfig extends ProviderConfig {
+  driver: 'whatsapp'
+  phoneNumberId: string
+  accessToken: string
+  appSecret: string
+  verifyToken: string
+  /** Defaults to `v20.0`. */
+  apiVersion?: string
+  flows?: WhatsAppFlowsConfig
+}

package/src/drivers/whatsapp/whatsapp_driver.ts

@@ -0,0 +1,111 @@
+/**
+ * `WhatsAppDriver` — `InstantDriver` for the WhatsApp Cloud API.
+ *
+ * Wraps `MetaGraphClient` for `/messages` posts. No `reply` /
+ * `multicast` / `broadcast` — the Cloud API has no native batch
+ * fan-out; apps loop `push` with their own rate-limit policy.
+ *
+ * `profile` returns whatever name the inbound contact carried —
+ * Cloud has no per-user profile endpoint comparable to LINE.
+ * Apps that need names should read them off webhook payloads
+ * and cache.
+ */
+
+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 { MetaGraphClient } from '../../internal/meta/meta_graph_client.ts'
+import type { WhatsAppProviderConfig } from './whatsapp_config.ts'
+import { toWhatsAppPayload } from './whatsapp_message_mapper.ts'
+import {
+  parseWhatsAppWebhook,
+  verifyWhatsAppChallenge,
+  verifyWhatsAppSignature,
+} from './whatsapp_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.interactive',
+  'send.templateParams',
+  'send.template',
+  'send.quickReplies',
+  'push',
+  'miniApp',
+  'webhook.signature',
+  'webhook.parse',
+])
+
+export interface WhatsAppDriverOptions {
+  instanceName: string
+  config: WhatsAppProviderConfig
+  /** Inject a pre-built graph client (tests). */
+  client?: MetaGraphClient
+}
+
+export class WhatsAppDriver implements InstantDriver {
+  readonly name = 'whatsapp'
+  readonly instanceName: string
+  readonly capabilities = DEFAULT_CAPABILITIES
+  readonly webhook: WebhookOps
+  private readonly client: MetaGraphClient
+  private readonly phoneNumberId: string
+
+  constructor(options: WhatsAppDriverOptions) {
+    const { instanceName, config } = options
+    requireField(config.phoneNumberId, 'phoneNumberId', instanceName)
+    requireField(config.accessToken, 'accessToken', instanceName)
+    requireField(config.appSecret, 'appSecret', instanceName)
+    requireField(config.verifyToken, 'verifyToken', instanceName)
+    this.instanceName = instanceName
+    this.phoneNumberId = config.phoneNumberId
+    this.client =
+      options.client ??
+      new MetaGraphClient({
+        accessToken: config.accessToken,
+        ...(config.apiVersion ? { apiVersion: config.apiVersion } : {}),
+        provider: 'whatsapp',
+      })
+    const appSecret = config.appSecret
+    const verifyToken = config.verifyToken
+    this.webhook = {
+      verifySignature: (rawBody, header) => verifyWhatsAppSignature(rawBody, header, appSecret),
+      parse: (rawBody) => parseWhatsAppWebhook(rawBody),
+      verifyChallenge: (params) => verifyWhatsAppChallenge(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 = toWhatsAppPayload(to, message)
+    const response = await this.client.post<{ messages?: Array<{ id: string }> }>(
+      `/${this.phoneNumberId}/messages`,
+      body,
+      'send',
+    )
+    return {
+      provider: 'whatsapp',
+      accepted: true,
+      ...(response.messages?.[0]?.id ? { messageId: response.messages[0].id } : {}),
+      raw: response,
+    }
+  }
+}
+
+function requireField(value: string | undefined, field: string, instanceName: string): void {
+  if (!value) {
+    throw new InstantProviderError(
+      `WhatsAppDriver: \`${field}\` is required for provider "${instanceName}".`,
+      { provider: 'whatsapp', operation: 'init', status: 500 },
+    )
+  }
+}

package/src/drivers/whatsapp/whatsapp_message_mapper.ts

@@ -0,0 +1,157 @@
+/**
+ * Map `OutgoingMessage` → WhatsApp Cloud `/messages` payload.
+ *
+ * WhatsApp's send endpoint takes one message per call — the
+ * mapper returns the message body and the driver POSTs once.
+ * Text + attachment → caller decides; the mapper emits one
+ * payload per call. Apps that want both send the text first
+ * and the attachment second (or the other way around).
+ *
+ * Provider-native escape hatches via `raw`:
+ *   - `raw.template?: { name, language, components }` → `template` HSM
+ *   - `raw.list?: { header?, body, footer?, button, sections[] }` → `interactive.list`
+ *   - `raw.flow?: { token, screen, cta, mode? }` → `interactive.flow`
+ *   - `raw.contextMessageId?: string` → `context.message_id` (in-thread reply)
+ */
+
+import { InstantProviderError } from '../../errors.ts'
+import type { Attachment, OutgoingMessage, QuickReply } from '../../message.ts'
+
+interface WhatsAppRawExtras {
+  template?: { name: string; language: string; components?: unknown[] }
+  list?: {
+    header?: string
+    body: string
+    footer?: string
+    button: string
+    sections: Array<{ title?: string; rows: Array<{ id: string; title: string; description?: string }> }>
+  }
+  flow?: { token: string; screen?: string; cta: string; mode?: 'draft' | 'published'; data?: Record<string, unknown> }
+  contextMessageId?: string
+}
+
+export function toWhatsAppPayload(to: string, message: OutgoingMessage): Record<string, unknown> {
+  const raw = (message.raw ?? {}) as WhatsAppRawExtras
+  const base: Record<string, unknown> = {
+    messaging_product: 'whatsapp',
+    recipient_type: 'individual',
+    to,
+    ...(raw.contextMessageId ? { context: { message_id: raw.contextMessageId } } : {}),
+  }
+
+  if (raw.template) {
+    return {
+      ...base,
+      type: 'template',
+      template: {
+        name: raw.template.name,
+        language: { code: raw.template.language },
+        ...(raw.template.components ? { components: raw.template.components } : {}),
+      },
+    }
+  }
+
+  if (raw.flow) {
+    return {
+      ...base,
+      type: 'interactive',
+      interactive: {
+        type: 'flow',
+        body: { text: message.text ?? '' },
+        action: {
+          name: 'flow',
+          parameters: {
+            flow_token: raw.flow.token,
+            flow_cta: raw.flow.cta,
+            flow_action: 'navigate',
+            ...(raw.flow.screen ? { flow_action_payload: { screen: raw.flow.screen, ...(raw.flow.data ? { data: raw.flow.data } : {}) } } : {}),
+            mode: raw.flow.mode ?? 'published',
+          },
+        },
+      },
+    }
+  }
+
+  if (raw.list) {
+    return {
+      ...base,
+      type: 'interactive',
+      interactive: {
+        type: 'list',
+        ...(raw.list.header ? { header: { type: 'text', text: raw.list.header } } : {}),
+        body: { text: raw.list.body },
+        ...(raw.list.footer ? { footer: { text: raw.list.footer } } : {}),
+        action: { button: raw.list.button, sections: raw.list.sections },
+      },
+    }
+  }
+
+  if (message.quickReplies && message.quickReplies.length > 0) {
+    return {
+      ...base,
+      type: 'interactive',
+      interactive: buildInteractiveButtons(message.text, message.quickReplies),
+    }
+  }
+
+  const attachment = message.attachments?.[0]
+  if (attachment) return { ...base, ...attachmentPayload(attachment, message.text) }
+
+  if (!message.text) {
+    throw new InstantProviderError(
+      'WhatsApp send requires `text`, an attachment, or a `raw.template`/`raw.list`/`raw.flow`.',
+      { provider: 'whatsapp', operation: 'send', status: 400 },
+    )
+  }
+
+  return { ...base, type: 'text', text: { body: message.text } }
+}
+
+function buildInteractiveButtons(
+  text: string | undefined,
+  quickReplies: QuickReply[],
+): Record<string, unknown> {
+  if (quickReplies.length > 3) {
+    throw new InstantProviderError(
+      'WhatsApp interactive buttons support at most 3 quick replies. Use `raw.list` for longer menus.',
+      { provider: 'whatsapp', operation: 'send', status: 400 },
+    )
+  }
+  const buttons = quickReplies.map((qr, i) => ({
+    type: 'reply',
+    reply: { id: qr.action.type === 'postback' ? qr.action.data : `qr_${i}`, title: qr.label.slice(0, 20) },
+  }))
+  return {
+    type: 'button',
+    body: { text: text ?? '' },
+    action: { buttons },
+  }
+}
+
+function attachmentPayload(a: Attachment, text: string | undefined): Record<string, unknown> {
+  switch (a.type) {
+    case 'image':
+      return { type: 'image', image: { link: a.url, ...(text ? { caption: text } : {}) } }
+    case 'video':
+      return { type: 'video', video: { link: a.url, ...(text ? { caption: text } : {}) } }
+    case 'audio':
+      return { type: 'audio', audio: { link: a.url } }
+    case 'file':
+      return {
+        type: 'document',
+        document: { link: a.url, ...(a.fileName ? { filename: a.fileName } : {}), ...(text ? { caption: text } : {}) },
+      }
+    case 'location':
+      return {
+        type: 'location',
+        location: {
+          latitude: a.latitude,
+          longitude: a.longitude,
+          ...(a.title ? { name: a.title } : {}),
+          ...(a.address ? { address: a.address } : {}),
+        },
+      }
+    case 'sticker':
+      return { type: 'sticker', sticker: { id: a.stickerId } }
+  }
+}

package/src/drivers/whatsapp/whatsapp_provider.ts

@@ -0,0 +1,31 @@
+/**
+ * `WhatsAppInstantProvider` — `ServiceProvider` that registers
+ * the WhatsApp Cloud 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 { WhatsAppProviderConfig } from './whatsapp_config.ts'
+import { WhatsAppDriver } from './whatsapp_driver.ts'
+
+export class WhatsAppInstantProvider extends ServiceProvider {
+  override readonly name = 'instant-whatsapp'
+  override readonly dependencies = ['instant']
+
+  override register(app: Application): void {
+    const manager = app.resolve(InstantManager)
+    manager.extend('whatsapp', ({ instanceName, config }) => {
+      const cfg = config as WhatsAppProviderConfig
+      for (const field of ['phoneNumberId', 'accessToken', 'appSecret', 'verifyToken'] as const) {
+        if (!cfg[field]) {
+          throw new InstantConfigError(
+            `WhatsAppInstantProvider: \`${field}\` is required for provider "${instanceName}".`,
+            { context: { instanceName, field } },
+          )
+        }
+      }
+      return new WhatsAppDriver({ instanceName, config: cfg })
+    })
+  }
+}

package/src/drivers/whatsapp/whatsapp_webhook.ts

@@ -0,0 +1,170 @@
+/**
+ * WhatsApp webhook — signature, GET-handshake, and parser.
+ *
+ * Signature delegates to the shared Meta verifier
+ * (`X-Hub-Signature-256` over the raw body).
+ *
+ * Parser walks `entry[].changes[].value.messages[]` and emits
+ * normalized `WebhookEvent`s. Status callbacks
+ * (`value.statuses[]`) and contacts/order events map to
+ * `UnknownEvent`.
+ */
+
+import { WebhookSignatureError } from '../../errors.ts'
+import { verifyMetaChallenge } from '../../internal/meta/meta_webhook_challenge.ts'
+import { verifyMetaSignature } from '../../internal/meta/meta_signature.ts'
+import type {
+  LocationMessageEvent,
+  MediaMessageEvent,
+  PostbackEvent,
+  StickerMessageEvent,
+  TextMessageEvent,
+  UnknownEvent,
+  WebhookEvent,
+  WebhookEventBase,
+} from '../../webhook_event.ts'
+
+export function verifyWhatsAppSignature(
+  rawBody: string,
+  header: string | null | undefined,
+  appSecret: string,
+): boolean {
+  return verifyMetaSignature(rawBody, header, appSecret)
+}
+
+export function verifyWhatsAppChallenge(
+  params: Record<string, string | undefined>,
+  verifyToken: string,
+): string | null {
+  return verifyMetaChallenge(params, verifyToken)
+}
+
+interface WAPayload {
+  object?: string
+  entry?: WAEntry[]
+}
+interface WAEntry {
+  id: string
+  changes?: WAChange[]
+}
+interface WAChange {
+  field: string
+  value?: WAValue
+}
+interface WAValue {
+  messaging_product?: string
+  metadata?: { phone_number_id: string; display_phone_number: string }
+  contacts?: Array<{ wa_id: string; profile?: { name?: string } }>
+  messages?: WAMessage[]
+  statuses?: unknown[]
+}
+interface WAMessage {
+  id: string
+  from: string
+  timestamp: string
+  type: string
+  text?: { body: string }
+  image?: { id: string; mime_type?: string }
+  video?: { id: string; mime_type?: string }
+  audio?: { id: string; mime_type?: string }
+  document?: { id: string; mime_type?: string; filename?: string }
+  sticker?: { id: string }
+  location?: { latitude: number; longitude: number; name?: string; address?: string }
+  interactive?: {
+    type: 'button_reply' | 'list_reply' | 'nfm_reply'
+    button_reply?: { id: string; title: string }
+    list_reply?: { id: string; title: string; description?: string }
+    nfm_reply?: { response_json: string; name?: string }
+  }
+  button?: { payload: string; text: string }
+}
+
+export function parseWhatsAppWebhook(rawBody: string): WebhookEvent[] {
+  let payload: WAPayload
+  try {
+    payload = JSON.parse(rawBody) as WAPayload
+  } catch (cause) {
+    throw new WebhookSignatureError('WhatsApp webhook body is not valid JSON.', { cause })
+  }
+  const events: WebhookEvent[] = []
+  for (const entry of payload.entry ?? []) {
+    for (const change of entry.changes ?? []) {
+      const value = change.value
+      if (!value) continue
+      for (const m of value.messages ?? []) {
+        const event = mapMessage(m, value)
+        if (event) events.push(event)
+      }
+    }
+  }
+  return events
+}
+
+function mapMessage(m: WAMessage, value: WAValue): WebhookEvent | undefined {
+  const base: WebhookEventBase = {
+    provider: 'whatsapp',
+    userId: m.from,
+    timestamp: new Date(Number.parseInt(m.timestamp, 10) * 1000),
+    source: 'user',
+    raw: { message: m, contacts: value.contacts ?? [] },
+  }
+  switch (m.type) {
+    case 'text': {
+      if (!m.text) break
+      const e: TextMessageEvent = { ...base, type: 'message.text', text: m.text.body, messageId: m.id }
+      return e
+    }
+    case 'image':
+    case 'video':
+    case 'audio':
+    case 'document': {
+      const mapped =
+        m.type === 'image'
+          ? 'message.image'
+          : m.type === 'video'
+            ? 'message.video'
+            : m.type === 'audio'
+              ? 'message.audio'
+              : 'message.file'
+      const e: MediaMessageEvent = { ...base, type: mapped, messageId: m.id }
+      return e
+    }
+    case 'sticker': {
+      const e: StickerMessageEvent = {
+        ...base,
+        type: 'message.sticker',
+        messageId: m.id,
+        ...(m.sticker?.id ? { stickerId: m.sticker.id } : {}),
+      }
+      return e
+    }
+    case 'location': {
+      if (!m.location) break
+      const e: LocationMessageEvent = {
+        ...base,
+        type: 'message.location',
+        messageId: m.id,
+        latitude: m.location.latitude,
+        longitude: m.location.longitude,
+        ...(m.location.name ? { title: m.location.name } : {}),
+        ...(m.location.address ? { address: m.location.address } : {}),
+      }
+      return e
+    }
+    case 'interactive': {
+      const data =
+        m.interactive?.button_reply?.id ??
+        m.interactive?.list_reply?.id ??
+        m.interactive?.nfm_reply?.response_json ??
+        ''
+      const e: PostbackEvent = { ...base, type: 'postback', data }
+      return e
+    }
+    case 'button': {
+      const e: PostbackEvent = { ...base, type: 'postback', data: m.button?.payload ?? '' }
+      return e
+    }
+  }
+  const fallback: UnknownEvent = { ...base, type: 'unknown' }
+  return fallback
+}

package/src/drivers/zalo/index.ts

@@ -0,0 +1,16 @@
+// Public API of `@strav/instant/zalo`.
+
+export type {
+  ZaloProviderConfig,
+  ZaloTokenStore,
+  ZnsTemplateMeta,
+} from './zalo_config.ts'
+export { ZaloDriver, type ZaloDriverOptions } from './zalo_driver.ts'
+export {
+  toZaloEnvelope,
+  type ZaloMessageEnvelope,
+  type ZaloMessageType,
+} from './zalo_message_mapper.ts'
+export { miniAppDeepLink } from './zalo_mini_app.ts'
+export { ZaloInstantProvider } from './zalo_provider.ts'
+export { parseZaloWebhook, verifyZaloSignature, type ZaloSignatureOptions } from './zalo_webhook.ts'

package/src/drivers/zalo/zalo_config.ts

@@ -0,0 +1,37 @@
+/**
+ * `ZaloProviderConfig` — config shape consumed by
+ * `ZaloInstantProvider`.
+ *
+ * Zalo OA access tokens are short-lived (~1h) and must be
+ * refreshed using the long-lived `refreshToken`. Apps that
+ * deploy long-running workers should pass a `tokenStore` so
+ * the driver can persist refreshed credentials across
+ * processes; otherwise the in-memory copy is the only
+ * source-of-truth and refreshing is the app's responsibility.
+ */
+
+import type { ProviderConfig } from '../../types.ts'
+
+export interface ZaloTokenStore {
+  load(): Promise<{ accessToken: string; refreshToken?: string } | null>
+  save(creds: { accessToken: string; refreshToken?: string }): Promise<void>
+}
+
+export interface ZnsTemplateMeta {
+  templateId: string
+  /** Documented param keys for clearer downstream type errors. */
+  params: readonly string[]
+}
+
+export interface ZaloProviderConfig extends ProviderConfig {
+  driver: 'zalo'
+  oaId: string
+  accessToken: string
+  appId: string
+  appSecret: string
+  refreshToken?: string
+  znsTemplates?: Record<string, ZnsTemplateMeta>
+  tokenStore?: ZaloTokenStore
+  /** Override OA API base (defaults to `https://openapi.zalo.me`). */
+  apiBaseURL?: string
+}