@strav/instant 1.0.0-alpha.42

package/src/drivers/zalo/zalo_driver.ts

@@ -0,0 +1,130 @@
+/**
+ * `ZaloDriver` — `InstantDriver` for the Zalo Official Account
+ * Messaging API. Uses `fetch` (no SDK dependency).
+ *
+ * Zalo's access token is short-lived. The driver re-uses
+ * `config.accessToken` as-is and lets the app refresh via
+ * `tokenStore`; refresh handling is out of scope for the
+ * driver itself (apps wire a cron + `tokenStore.save`).
+ */
+
+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 { ZaloProviderConfig } from './zalo_config.ts'
+import { toZaloEnvelope, type ZaloMessageType } from './zalo_message_mapper.ts'
+import { parseZaloWebhook, verifyZaloSignature } from './zalo_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.template',
+  'send.templateParams',
+  'send.quickReplies',
+  'push',
+  'profile',
+  'miniApp',
+  'webhook.signature',
+  'webhook.parse',
+])
+
+const ENDPOINT_PATH: Record<ZaloMessageType, string> = {
+  cs: '/v3.0/oa/message/cs',
+  transaction: '/v3.0/oa/message/transaction',
+  zns: '/v2.0/oa/message/zns',
+}
+
+export interface ZaloDriverOptions {
+  instanceName: string
+  config: ZaloProviderConfig
+}
+
+export class ZaloDriver implements InstantDriver {
+  readonly name = 'zalo'
+  readonly instanceName: string
+  readonly capabilities = DEFAULT_CAPABILITIES
+  readonly webhook: WebhookOps
+  private accessToken: string
+  private readonly base: string
+
+  constructor(options: ZaloDriverOptions) {
+    const { instanceName, config } = options
+    for (const field of ['oaId', 'accessToken', 'appId', 'appSecret'] as const) {
+      if (!config[field]) {
+        throw new InstantProviderError(
+          `ZaloDriver: \`${field}\` is required for provider "${instanceName}".`,
+          { provider: 'zalo', operation: 'init', status: 500 },
+        )
+      }
+    }
+    this.instanceName = instanceName
+    this.accessToken = config.accessToken
+    this.base = config.apiBaseURL ?? 'https://openapi.zalo.me'
+    const appId = config.appId
+    const appSecret = config.appSecret
+    this.webhook = {
+      verifySignature: (rawBody) => verifyZaloSignature(rawBody, { appId, appSecret }),
+      parse: (rawBody) => parseZaloWebhook(rawBody),
+    }
+  }
+
+  setAccessToken(token: string): void {
+    this.accessToken = token
+  }
+
+  async send(to: string, message: OutgoingMessage): Promise<SendResult> {
+    return this.push(to, message)
+  }
+
+  async push(to: string, message: OutgoingMessage): Promise<SendResult> {
+    const envelope = toZaloEnvelope(to, message)
+    const response = await this.invoke<{ data?: { message_id?: string }; error?: number; message?: string }>(
+      ENDPOINT_PATH[envelope.endpoint],
+      envelope.body,
+      `send.${envelope.endpoint}`,
+    )
+    if (typeof response.error === 'number' && response.error !== 0) {
+      throw new InstantProviderError(`Zalo API returned error ${response.error}: ${response.message ?? ''}`.trim(), {
+        provider: 'zalo',
+        operation: `send.${envelope.endpoint}`,
+        context: { error: response.error, message: response.message },
+      })
+    }
+    return {
+      provider: 'zalo',
+      accepted: true,
+      ...(response.data?.message_id ? { messageId: response.data.message_id } : {}),
+      raw: response,
+    }
+  }
+
+  async profile(userId: string): Promise<UserProfile> {
+    const response = await this.invoke<{
+      data?: { user_id?: string; display_name?: string; avatar?: string }
+    }>('/v2.0/oa/getprofile', { user_id: userId }, 'profile')
+    const r = response.data ?? {}
+    return {
+      userId: r.user_id ?? userId,
+      ...(r.display_name ? { displayName: r.display_name } : {}),
+      ...(r.avatar ? { pictureUrl: r.avatar } : {}),
+      raw: response,
+    }
+  }
+
+  private invoke<T>(path: string, body: Record<string, unknown>, operation: string): Promise<T> {
+    return fetchJson<T>(`${this.base}${path}`, {
+      method: 'POST',
+      headers: { access_token: this.accessToken, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      provider: 'zalo',
+      operation,
+    })
+  }
+}

package/src/drivers/zalo/zalo_message_mapper.ts

@@ -0,0 +1,146 @@
+/**
+ * Map `OutgoingMessage` → Zalo OA message body.
+ *
+ * Two endpoints:
+ *   - `/v3.0/oa/message/cs` — customer-service (within 24h
+ *     reply window). Default for `send`/`push`.
+ *   - `/v3.0/oa/message/transaction` — transactional sends
+ *     outside the window. Requires `raw.zns`-style template
+ *     approval.
+ *
+ * ZNS (Zalo Notification Service) sends go through a different
+ * URL path; the driver handles routing. The mapper produces the
+ * body only.
+ *
+ * Provider-native escape hatches via `raw`:
+ *   - `raw.zns?: { template_id, template_data }` → ZNS template send
+ *   - `raw.messageType?: 'cs' | 'transaction'` (default 'cs')
+ */
+
+import { InstantProviderError } from '../../errors.ts'
+import type { Attachment, OutgoingMessage, QuickReply } from '../../message.ts'
+
+export type ZaloMessageType = 'cs' | 'transaction' | 'zns'
+
+export interface ZaloMessageEnvelope {
+  endpoint: ZaloMessageType
+  body: Record<string, unknown>
+}
+
+interface ZaloRawExtras {
+  zns?: { template_id: string; template_data: Record<string, string>; tracking_id?: string }
+  messageType?: 'cs' | 'transaction'
+}
+
+export function toZaloEnvelope(to: string, message: OutgoingMessage): ZaloMessageEnvelope {
+  const raw = (message.raw ?? {}) as ZaloRawExtras
+
+  if (raw.zns) {
+    return {
+      endpoint: 'zns',
+      body: {
+        phone: to,
+        template_id: raw.zns.template_id,
+        template_data: raw.zns.template_data,
+        ...(raw.zns.tracking_id ? { tracking_id: raw.zns.tracking_id } : {}),
+      },
+    }
+  }
+
+  const endpoint: ZaloMessageType = raw.messageType ?? 'cs'
+  const recipient = { user_id: to }
+  const attachment = message.attachments?.[0]
+  const quickReplies = message.quickReplies
+
+  if (attachment) {
+    return {
+      endpoint,
+      body: { recipient, message: attachmentBody(attachment, message.text, quickReplies) },
+    }
+  }
+
+  if (quickReplies && quickReplies.length > 0) {
+    return {
+      endpoint,
+      body: {
+        recipient,
+        message: {
+          text: message.text ?? '',
+          attachment: { type: 'template', payload: listTemplate(quickReplies) },
+        },
+      },
+    }
+  }
+
+  if (!message.text) {
+    throw new InstantProviderError(
+      'Zalo send requires `text`, an attachment, or `raw.zns`.',
+      { provider: 'zalo', operation: 'send', status: 400 },
+    )
+  }
+
+  return { endpoint, body: { recipient, message: { text: message.text } } }
+}
+
+function attachmentBody(
+  a: Attachment,
+  text: string | undefined,
+  quickReplies: QuickReply[] | undefined,
+): Record<string, unknown> {
+  const baseText = text ?? ''
+  switch (a.type) {
+    case 'image':
+      return {
+        text: baseText,
+        attachment: { type: 'template', payload: { template_type: 'media', elements: [{ media_type: 'image', url: a.url }] } },
+      }
+    case 'video':
+      return {
+        text: baseText,
+        attachment: { type: 'template', payload: { template_type: 'media', elements: [{ media_type: 'video', url: a.url }] } },
+      }
+    case 'file':
+      return {
+        text: baseText,
+        attachment: { type: 'file', payload: { url: a.url } },
+      }
+    case 'audio':
+      // Zalo OA has no first-class audio bubble — surface as a file.
+      return { text: baseText, attachment: { type: 'file', payload: { url: a.url } } }
+    case 'location':
+      return {
+        text: baseText || a.title || 'Location',
+        attachment: {
+          type: 'template',
+          payload: { template_type: 'request_user_info', elements: [{ id: 'location', text: a.title, address: a.address }] },
+        },
+      }
+    case 'sticker':
+      return { text: baseText, sticker: { id: a.stickerId } }
+    default:
+      return quickReplies
+        ? { text: baseText, attachment: { type: 'template', payload: listTemplate(quickReplies) } }
+        : { text: baseText }
+  }
+}
+
+function listTemplate(quickReplies: QuickReply[]): Record<string, unknown> {
+  return {
+    template_type: 'list',
+    elements: quickReplies.map((qr) => {
+      const element: Record<string, unknown> = { title: qr.label }
+      switch (qr.action.type) {
+        case 'postback':
+          element['default_action'] = { type: 'oa.query.hide', payload: qr.action.data }
+          break
+        case 'uri':
+          element['default_action'] = { type: 'oa.open.url', url: qr.action.uri }
+          break
+        case 'message':
+          element['default_action'] = { type: 'oa.query.show', payload: qr.action.text }
+          break
+      }
+      return element
+    }),
+  }
+}

package/src/drivers/zalo/zalo_mini_app.ts

@@ -0,0 +1,17 @@
+/**
+ * Zalo Mini App helpers.
+ *
+ * `miniAppDeepLink(appId, path, params)` builds a deep link
+ * that opens a Zalo Mini App on Android/iOS. Send via a list
+ * template with an `oa.open.url` action.
+ */
+
+export function miniAppDeepLink(
+  appId: string,
+  path: string,
+  params: Record<string, string> = {},
+): string {
+  const search = new URLSearchParams(params).toString()
+  const safePath = path.startsWith('/') ? path : `/${path}`
+  return `https://zalo.me/s/${encodeURIComponent(appId)}${safePath}${search ? `?${search}` : ''}`
+}

package/src/drivers/zalo/zalo_provider.ts

@@ -0,0 +1,31 @@
+/**
+ * `ZaloInstantProvider` — `ServiceProvider` that registers
+ * the Zalo OA 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 { ZaloProviderConfig } from './zalo_config.ts'
+import { ZaloDriver } from './zalo_driver.ts'
+
+export class ZaloInstantProvider extends ServiceProvider {
+  override readonly name = 'instant-zalo'
+  override readonly dependencies = ['instant']
+
+  override register(app: Application): void {
+    const manager = app.resolve(InstantManager)
+    manager.extend('zalo', ({ instanceName, config }) => {
+      const cfg = config as ZaloProviderConfig
+      for (const field of ['oaId', 'accessToken', 'appId', 'appSecret'] as const) {
+        if (!cfg[field]) {
+          throw new InstantConfigError(
+            `ZaloInstantProvider: \`${field}\` is required for provider "${instanceName}".`,
+            { context: { instanceName, field } },
+          )
+        }
+      }
+      return new ZaloDriver({ instanceName, config: cfg })
+    })
+  }
+}

package/src/drivers/zalo/zalo_webhook.ts

@@ -0,0 +1,139 @@
+/**
+ * Zalo OA webhook — signature + parse.
+ *
+ * Signature: Zalo OA posts a `mac` field inside the JSON body
+ * computed as `HMAC_SHA256(<appId><event_name><timestamp>, appSecret)`
+ * (hex). Apps verify by recomputing and constant-time comparing.
+ *
+ * ⚠️ The exact signature scheme has shifted between Zalo OA
+ * versions. The verifier is isolated to one function — if Zalo
+ * ships a v2 scheme, swap the formula here. The driver passes
+ * the raw body so the verifier can re-parse and read the
+ * relevant fields.
+ *
+ * Parse: maps `event_name` to the framework's WebhookEvent
+ * union. Anything unknown → UnknownEvent.
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { WebhookSignatureError } from '../../errors.ts'
+import type {
+  FollowEvent,
+  LocationMessageEvent,
+  MediaMessageEvent,
+  PostbackEvent,
+  StickerMessageEvent,
+  TextMessageEvent,
+  UnknownEvent,
+  WebhookEvent,
+  WebhookEventBase,
+} from '../../webhook_event.ts'
+
+export interface ZaloSignatureOptions {
+  appId: string
+  appSecret: string
+}
+
+interface ZaloWebhookBody {
+  app_id?: string
+  event_name?: string
+  timestamp?: string
+  sender?: { id: string }
+  recipient?: { id: string }
+  message?: {
+    msg_id?: string
+    text?: string
+    attachments?: Array<{ type: string; payload?: Record<string, unknown> }>
+  }
+  mac?: string
+}
+
+export function verifyZaloSignature(rawBody: string, options: ZaloSignatureOptions): boolean {
+  let parsed: ZaloWebhookBody
+  try {
+    parsed = JSON.parse(rawBody) as ZaloWebhookBody
+  } catch {
+    return false
+  }
+  const { mac, event_name, timestamp } = parsed
+  if (!mac || !event_name || !timestamp) return false
+  if (parsed.app_id && parsed.app_id !== options.appId) return false
+  const data = `${options.appId}${event_name}${timestamp}`
+  const expected = createHmac('sha256', options.appSecret).update(data).digest('hex')
+  if (mac.length !== expected.length) return false
+  return timingSafeEqual(Buffer.from(mac, 'hex'), Buffer.from(expected, 'hex'))
+}
+
+export function parseZaloWebhook(rawBody: string): WebhookEvent[] {
+  let payload: ZaloWebhookBody
+  try {
+    payload = JSON.parse(rawBody) as ZaloWebhookBody
+  } catch (cause) {
+    throw new WebhookSignatureError('Zalo webhook body is not valid JSON.', { cause })
+  }
+  const event = mapEvent(payload)
+  return event ? [event] : []
+}
+
+function mapEvent(p: ZaloWebhookBody): WebhookEvent | undefined {
+  if (!p.event_name) return undefined
+  const senderId = p.sender?.id
+  if (!senderId) return undefined
+  const base: WebhookEventBase = {
+    provider: 'zalo',
+    userId: senderId,
+    timestamp: p.timestamp ? new Date(Number.parseInt(p.timestamp, 10)) : new Date(),
+    source: 'user',
+    raw: p,
+  }
+  const messageId = p.message?.msg_id ?? ''
+
+  switch (p.event_name) {
+    case 'user_send_text': {
+      const e: TextMessageEvent = { ...base, type: 'message.text', text: p.message?.text ?? '', messageId }
+      return e
+    }
+    case 'user_send_image':
+      return { ...base, type: 'message.image', messageId } as MediaMessageEvent
+    case 'user_send_gif':
+    case 'user_send_video':
+      return { ...base, type: 'message.video', messageId } as MediaMessageEvent
+    case 'user_send_audio':
+      return { ...base, type: 'message.audio', messageId } as MediaMessageEvent
+    case 'user_send_file':
+      return { ...base, type: 'message.file', messageId } as MediaMessageEvent
+    case 'user_send_sticker': {
+      const e: StickerMessageEvent = { ...base, type: 'message.sticker', messageId }
+      return e
+    }
+    case 'user_send_location': {
+      const att = p.message?.attachments?.[0]?.payload as { coordinates?: { latitude: number; longitude: number } } | undefined
+      if (!att?.coordinates) return { ...base, type: 'unknown' }
+      const e: LocationMessageEvent = {
+        ...base,
+        type: 'message.location',
+        messageId,
+        latitude: att.coordinates.latitude,
+        longitude: att.coordinates.longitude,
+      }
+      return e
+    }
+    case 'user_click_chatnow':
+    case 'user_submit_info':
+    case 'user_send_link': {
+      const data = (p.message?.attachments?.[0]?.payload?.['payload'] as string | undefined) ?? p.message?.text ?? ''
+      const e: PostbackEvent = { ...base, type: 'postback', data }
+      return e
+    }
+    case 'follow': {
+      const e: FollowEvent = { ...base, type: 'follow' }
+      return e
+    }
+    case 'unfollow': {
+      const e: FollowEvent = { ...base, type: 'unfollow' }
+      return e
+    }
+  }
+  const fallback: UnknownEvent = { ...base, type: 'unknown' }
+  return fallback
+}

package/src/errors.ts

@@ -0,0 +1,122 @@
+/**
+ * `InstantError` hierarchy — typed wrappers for failures across
+ * the instant-messaging stack. Vendor-native errors (LINE API
+ * failures, WhatsApp rejections) are preserved on `.cause` so
+ * apps can still `instanceof` the underlying type for retry /
+ * recovery logic; the wrapping just gives the framework a
+ * consistent `StravError` for the standard exception handler.
+ *
+ * Subclasses:
+ *
+ *   - `InstantConfigError` — `config.instant` missing required
+ *     fields. Thrown at boot from `InstantProvider`.
+ *
+ *   - `ProviderUnsupportedError` — driver doesn't implement the
+ *     requested operation (e.g. `messenger.flex(...)`). Thrown
+ *     synchronously so apps fail fast.
+ *
+ *   - `UnknownProviderError` — `instant.use('x')` for a name not
+ *     configured. 400 — usually a config bug.
+ *
+ *   - `WebhookSignatureError` — signature header missing or
+ *     doesn't verify. Webhook route returns 400; LINE retries.
+ *
+ *   - `InstantProviderError` — generic wrapper around a vendor
+ *     exception that doesn't map to a more specific subclass.
+ *     Preserves `.cause`; default status 502.
+ */
+
+import { StravError } from '@strav/kernel'
+
+export class InstantError extends StravError {
+  constructor(
+    message: string,
+    options: {
+      code?: string
+      status?: number
+      context?: Record<string, unknown>
+      cause?: unknown
+    } = {},
+  ) {
+    super(
+      message,
+      { code: options.code ?? 'instant.error', status: options.status ?? 500 },
+      {
+        ...(options.context ? { context: options.context } : {}),
+        ...(options.cause !== undefined ? { cause: options.cause } : {}),
+      },
+    )
+  }
+}
+
+export class InstantConfigError extends InstantError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'instant.config',
+      status: 500,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}
+
+export class UnknownProviderError extends InstantError {
+  constructor(name: string, available: readonly string[]) {
+    super(
+      `Instant provider "${name}" is not configured. Available: ${available.join(', ') || '<none>'}.`,
+      {
+        code: 'instant.unknown_provider',
+        status: 400,
+        context: { requested: name, available },
+      },
+    )
+  }
+}
+
+export class ProviderUnsupportedError extends InstantError {
+  constructor(provider: string, operation: string, options: { reason?: string } = {}) {
+    const trailer = options.reason ? ` ${options.reason}` : ''
+    super(`Instant provider "${provider}" does not support "${operation}".${trailer}`, {
+      code: 'instant.provider_unsupported',
+      status: 400,
+      context: { provider, operation, ...(options.reason ? { reason: options.reason } : {}) },
+    })
+  }
+}
+
+export class WebhookSignatureError extends InstantError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, {
+      code: 'instant.webhook_signature',
+      status: 400,
+      ...(options.context ? { context: options.context } : {}),
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}
+
+export class InstantProviderError extends InstantError {
+  constructor(
+    message: string,
+    options: {
+      provider: string
+      operation: string
+      context?: Record<string, unknown>
+      cause?: unknown
+      status?: number
+    },
+  ) {
+    super(message, {
+      code: 'instant.provider_error',
+      status: options.status ?? 502,
+      context: {
+        provider: options.provider,
+        operation: options.operation,
+        ...(options.context ?? {}),
+      },
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+// Public API of `@strav/instant`.
+//
+// V1: provider-agnostic instant-messaging abstraction —
+// normalized `OutgoingMessage` + `WebhookEvent` + multi-provider
+// routing. The LINE driver ships as a subpath at
+// `@strav/instant/line` with Flex builder, rich menus, beacons,
+// and LIFF ID-token verification. WhatsApp + Messenger drivers
+// come in follow-up slices.
+
+export {
+  InstantConfigError,
+  InstantError,
+  InstantProviderError,
+  ProviderUnsupportedError,
+  UnknownProviderError,
+  WebhookSignatureError,
+} from './errors.ts'
+export type { InstantCapability } from './instant_capabilities.ts'
+export type {
+  InstantDriver,
+  InstantDriverFactory,
+  UserProfile,
+  WebhookOps,
+} from './instant_driver.ts'
+export {
+  InstantManager,
+  type InstantManagerOptions,
+} from './instant_manager.ts'
+export { InstantProvider } from './instant_provider.ts'
+export type {
+  Attachment,
+  OutgoingMessage,
+  QuickReply,
+  SendResult,
+} from './message.ts'
+export type {
+  InstantConfig,
+  ProviderConfig,
+} from './types.ts'
+export type {
+  BeaconEvent,
+  FollowEvent,
+  JoinEvent,
+  LocationMessageEvent,
+  MediaMessageEvent,
+  PostbackEvent,
+  StickerMessageEvent,
+  TextMessageEvent,
+  UnknownEvent,
+  WebhookEvent,
+  WebhookEventBase,
+} from './webhook_event.ts'

package/src/instant_capabilities.ts

@@ -0,0 +1,49 @@
+/**
+ * `InstantCapability` — granular feature flags every driver declares
+ * in `driver.capabilities`. Apps that build provider-neutral flows
+ * branch on capability before calling:
+ *
+ *   if (instant.use('line').capabilities.has('send.flex')) { ... }
+ *
+ * Granularity is intentionally fine — one flag per non-trivial
+ * surface, not one per group — so e.g. WhatsApp can support
+ * `send.template` without claiming `send.flex`, and LINE can
+ * support `richMenu` and `beacon` without any analogue elsewhere.
+ *
+ * Drivers omit a capability when they can't fulfil it faithfully.
+ * Apps reach into provider-specific subpath imports
+ * (`@strav/instant/line`) when they need behaviour that doesn't
+ * map to a common capability.
+ */
+
+export type InstantCapability =
+  // outbound content shapes
+  | 'send.text'
+  | 'send.image'
+  | 'send.video'
+  | 'send.audio'
+  | 'send.file'
+  | 'send.location'
+  | 'send.sticker'
+  | 'send.quickReplies'
+  | 'send.template'
+  | 'send.templateParams'
+  | 'send.interactive'
+  | 'send.flex'
+  // outbound endpoints
+  | 'reply'
+  | 'push'
+  | 'multicast'
+  | 'broadcast'
+  // identity + relationship
+  | 'profile'
+  | 'loadingIndicator'
+  // platform-specific surfaces
+  | 'richMenu'
+  | 'beacon'
+  | 'liff'
+  | 'miniApp'
+  | 'persistentMenu'
+  // inbound
+  | 'webhook.signature'
+  | 'webhook.parse'