@strav/instant 1.0.0-alpha.42

package/src/instant_driver.ts

@@ -0,0 +1,109 @@
+/**
+ * `InstantDriver` — the driver contract every adapter implements.
+ *
+ * One driver represents a configured provider instance
+ * (`config.instant.providers['line']`). The manager holds one
+ * driver per configured name and routes send / reply / webhook
+ * calls into it.
+ *
+ * Methods drivers don't support throw `ProviderUnsupportedError`
+ * synchronously. The driver's `capabilities` set declares the
+ * supported surfaces — apps that branch on capability avoid the
+ * throw by checking first.
+ */
+
+import type { InstantCapability } from './instant_capabilities.ts'
+import type { OutgoingMessage, SendResult } from './message.ts'
+import type { WebhookEvent } from './webhook_event.ts'
+
+/**
+ * Inbound webhook verification + parsing. Drivers that lack a
+ * webhook surface (rare for an instant-messaging provider)
+ * declare neither `webhook.signature` nor `webhook.parse` and
+ * throw `ProviderUnsupportedError` from these methods.
+ */
+export interface WebhookOps {
+  /**
+   * Verify the provider signature against the raw request body.
+   * Returns `true` when the signature matches. Drivers throw
+   * `WebhookSignatureError` only when the header is missing /
+   * malformed; a clean mismatch returns `false` so the route
+   * can decide how to respond.
+   */
+  verifySignature(rawBody: string, signature: string | null | undefined): boolean
+  /**
+   * Parse a verified raw body into the framework's normalized
+   * `WebhookEvent` union. Drivers translate every event variant
+   * they can recognise; unknown shapes map to `{ type: 'unknown', raw }`.
+   */
+  parse(rawBody: string): WebhookEvent[]
+  /**
+   * Optional GET-handshake responder used by webhook providers
+   * that require URL verification before they post events
+   * (Meta Cloud / Send API). Receivers call this with the
+   * query params; the driver returns the challenge value to
+   * echo back when the verify token matches, or `null` to
+   * reject. Drivers without a handshake omit this method.
+   */
+  verifyChallenge?(params: Record<string, string | undefined>): string | null
+}
+
+/**
+ * Optional profile lookup. LINE / Messenger / WhatsApp all expose
+ * a "get user profile by id" endpoint with diverging fields;
+ * the driver returns whatever it can fill.
+ */
+export interface UserProfile {
+  userId: string
+  displayName?: string
+  pictureUrl?: string
+  statusMessage?: string
+  language?: string
+  raw?: unknown
+}
+
+export interface InstantDriver {
+  /** Driver identifier — matches the `driver:` discriminator in `ProviderConfig`. */
+  readonly name: string
+  /** App-chosen instance name (`config.instant.providers[name]`). */
+  readonly instanceName: string
+  /** Declared feature set. Apps check this to branch around `ProviderUnsupportedError`. */
+  readonly capabilities: ReadonlySet<InstantCapability>
+
+  /**
+   * Send a message to a single recipient. Whether this uses the
+   * provider's "push" endpoint, "send" endpoint, or a reply
+   * window is provider-defined; the common shape is "I have a
+   * recipient id, deliver this message."
+   */
+  send(to: string, message: OutgoingMessage): Promise<SendResult>
+
+  /**
+   * Reply to an inbound event within the provider's reply
+   * window. `replyToken` is provider-issued (LINE reply token,
+   * WhatsApp context message id, …).
+   */
+  reply?(replyToken: string, message: OutgoingMessage): Promise<SendResult>
+
+  /** Push to a recipient outside a reply window. Distinct from `send` only on providers that distinguish. */
+  push?(to: string, message: OutgoingMessage): Promise<SendResult>
+
+  /** Multicast — same message to many recipients. */
+  multicast?(to: readonly string[], message: OutgoingMessage): Promise<SendResult>
+
+  /** Broadcast — same message to every follower. */
+  broadcast?(message: OutgoingMessage): Promise<SendResult>
+
+  /** Fetch a profile from the provider. */
+  profile?(userId: string): Promise<UserProfile>
+
+  readonly webhook: WebhookOps
+}
+
+/** Factory the manager invokes for each configured provider. */
+export type InstantDriverFactory = (config: {
+  /** App-chosen instance name (`'line'`, `'line-marketing'`, …). */
+  instanceName: string
+  /** Provider-config object with `driver:` + driver-specific fields. */
+  config: Record<string, unknown> & { driver: string }
+}) => InstantDriver

package/src/instant_manager.ts

@@ -0,0 +1,113 @@
+/**
+ * `InstantManager` — the facade apps use for instant-messaging
+ * workflows.
+ *
+ * Mirrors the manager-pattern shared with `@strav/payment` and
+ * `@strav/notification`:
+ *
+ *   - **Drivers.** Apps declare providers in
+ *     `config.instant.providers`. The manager constructs each
+ *     driver lazily on first `use(name)` + memoizes. Adapter
+ *     packages register their factories via
+ *     `manager.extend(name, factory)`.
+ *
+ *   - **Default routing.** `manager.send(to, msg)` routes to the
+ *     default driver. `manager.use('marketing').send(...)`
+ *     targets a named one.
+ *
+ *   - **Webhooks.** `manager.verify(provider, rawBody, sig)` and
+ *     `manager.parseWebhook(provider, rawBody)` delegate into the
+ *     driver's `WebhookOps`. Apps wire these into their HTTP
+ *     route (one route per provider).
+ */
+
+import { InstantConfigError, UnknownProviderError } from './errors.ts'
+import type { InstantDriver, InstantDriverFactory } from './instant_driver.ts'
+import type { OutgoingMessage, SendResult } from './message.ts'
+import type { InstantConfig, ProviderConfig } from './types.ts'
+import type { WebhookEvent } from './webhook_event.ts'
+
+export interface InstantManagerOptions {
+  config: InstantConfig
+}
+
+export class InstantManager {
+  readonly config: InstantConfig
+
+  private readonly drivers = new Map<string, InstantDriver>()
+  private readonly extensions = new Map<string, InstantDriverFactory>()
+
+  constructor(options: InstantManagerOptions) {
+    const { config } = options
+    if (!config.providers[config.default]) {
+      throw new InstantConfigError(
+        `InstantManager: default provider "${config.default}" is not configured.`,
+        {
+          context: {
+            default: config.default,
+            available: Object.keys(config.providers),
+          },
+        },
+      )
+    }
+    this.config = config
+  }
+
+  // ─── Driver routing ──────────────────────────────────────────────────
+
+  /** Resolve a driver by app-chosen instance name (or the default when omitted). */
+  use(name?: string): InstantDriver {
+    const key = name ?? this.config.default
+    const cached = this.drivers.get(key)
+    if (cached) return cached
+
+    const cfg = this.config.providers[key]
+    if (!cfg) {
+      throw new UnknownProviderError(key, Object.keys(this.config.providers))
+    }
+    const ext = this.extensions.get(cfg.driver)
+    if (!ext) {
+      throw new InstantConfigError(
+        `InstantManager: unknown driver "${cfg.driver}" for provider "${key}". Register it via \`manager.extend("${cfg.driver}", factory)\` or install the matching adapter package.`,
+        { context: { driver: cfg.driver, available: [...this.extensions.keys()] } },
+      )
+    }
+    const driver = ext({
+      instanceName: key,
+      config: cfg as ProviderConfig & { driver: string },
+    })
+    this.drivers.set(key, driver)
+    return driver
+  }
+
+  /**
+   * Register a driver factory. Adapter packages call this from
+   * their ServiceProvider's `register()` step.
+   */
+  extend(driverName: string, factory: InstantDriverFactory): void {
+    this.extensions.set(driverName, factory)
+  }
+
+  /** Hand-wire a driver instance under an app-chosen name (tests / one-offs). */
+  useDriver(instanceName: string, driver: InstantDriver): void {
+    this.drivers.set(instanceName, driver)
+  }
+
+  // ─── Convenience delegates to the default driver ─────────────────────
+
+  send(to: string, message: OutgoingMessage): Promise<SendResult> {
+    return this.use().send(to, message)
+  }
+
+  // ─── Webhook routing ─────────────────────────────────────────────────
+
+  /** Verify a webhook signature using the named provider's driver. */
+  verify(provider: string, rawBody: string, signature: string | null | undefined): boolean {
+    return this.use(provider).webhook.verifySignature(rawBody, signature)
+  }
+
+  /** Parse a verified raw webhook body into the framework's normalized event union. */
+  parseWebhook(provider: string, rawBody: string): WebhookEvent[] {
+    return this.use(provider).webhook.parse(rawBody)
+  }
+}

package/src/instant_provider.ts

@@ -0,0 +1,45 @@
+/**
+ * `InstantProvider` — `ServiceProvider` that wires `InstantManager`
+ * into the container from `config.instant`.
+ *
+ * Adapter packages register their drivers separately via their
+ * own ServiceProvider (e.g. `LineInstantProvider`). Apps list
+ * the adapter providers AFTER `InstantProvider` in
+ * `bootstrap/providers.ts` — `register()` runs in declaration
+ * order, then `boot()` runs in the same order. Adapter
+ * `register()` calls `manager.extend(driver, factory)`; this
+ * provider's `boot()` eagerly resolves so config errors surface
+ * at startup.
+ */
+
+import { type Application, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import { InstantConfigError } from './errors.ts'
+import { InstantManager } from './instant_manager.ts'
+import type { InstantConfig } from './types.ts'
+
+export class InstantProvider extends ServiceProvider {
+  override readonly name = 'instant'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(InstantManager, (c) => {
+      const raw = c.resolve(ConfigRepository).get('instant') as InstantConfig | undefined
+      if (!raw) {
+        throw new InstantConfigError(
+          'InstantProvider: `config.instant` is missing. Add `config/instant.ts` with at least one provider.',
+        )
+      }
+      if (!raw.providers || Object.keys(raw.providers).length === 0) {
+        throw new InstantConfigError(
+          'InstantProvider: `config.instant.providers` is empty. Configure at least one provider.',
+        )
+      }
+      return new InstantManager({ config: raw })
+    })
+  }
+
+  override boot(app: Application): void {
+    // Force-resolve so config errors surface at boot, not on first send().
+    app.resolve(InstantManager)
+  }
+}

package/src/internal/fetch_json.ts

@@ -0,0 +1,58 @@
+/**
+ * Tiny `fetch` wrapper that returns parsed JSON or throws
+ * `InstantProviderError` with the provider/operation/status
+ * stamped on it. Used by every driver so vendor REST failures
+ * surface with the same shape regardless of which messenger
+ * tripped.
+ *
+ * The body comes back as `T` without runtime validation —
+ * callers know the endpoint shape and the framework's error
+ * handler is happy with whatever shape `.cause` carries.
+ */
+
+import { InstantProviderError } from '../errors.ts'
+
+export interface FetchJsonOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE'
+  headers?: Record<string, string>
+  body?: string | Uint8Array | FormData
+  provider: string
+  operation: string
+}
+
+export async function fetchJson<T>(url: string, options: FetchJsonOptions): Promise<T> {
+  const { provider, operation, method = 'GET', headers, body } = options
+  let response: Response
+  try {
+    response = await fetch(url, { method, headers, body })
+  } catch (cause) {
+    throw new InstantProviderError(`${provider} ${operation} request failed`, {
+      provider,
+      operation,
+      cause,
+    })
+  }
+  const text = await response.text()
+  if (!response.ok) {
+    throw new InstantProviderError(
+      `${provider} ${operation} returned HTTP ${response.status}`,
+      {
+        provider,
+        operation,
+        status: 502,
+        context: { httpStatus: response.status, body: text.slice(0, 1024) },
+      },
+    )
+  }
+  if (text.length === 0) return undefined as T
+  try {
+    return JSON.parse(text) as T
+  } catch (cause) {
+    throw new InstantProviderError(`${provider} ${operation} returned non-JSON body`, {
+      provider,
+      operation,
+      cause,
+      context: { body: text.slice(0, 256) },
+    })
+  }
+}

package/src/internal/meta/meta_graph_client.ts

@@ -0,0 +1,51 @@
+/**
+ * Thin typed wrapper around `graph.facebook.com/v<x>`.
+ * Shared by WhatsApp Cloud and Messenger Send API.
+ *
+ * Operations stamp `provider` + `operation` onto the
+ * `InstantProviderError` thrown by `fetchJson` so callers
+ * don't need to wrap again.
+ */
+
+import { fetchJson } from '../fetch_json.ts'
+
+export interface MetaGraphClientOptions {
+  accessToken: string
+  apiVersion?: string
+  provider: string
+}
+
+export class MetaGraphClient {
+  private readonly base: string
+  private readonly accessToken: string
+  private readonly provider: string
+
+  constructor(options: MetaGraphClientOptions) {
+    const version = options.apiVersion ?? 'v20.0'
+    this.base = `https://graph.facebook.com/${version}`
+    this.accessToken = options.accessToken
+    this.provider = options.provider
+  }
+
+  post<T>(path: string, body: unknown, operation: string): Promise<T> {
+    return fetchJson<T>(`${this.base}${path}`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+      provider: this.provider,
+      operation,
+    })
+  }
+
+  get<T>(path: string, operation: string): Promise<T> {
+    return fetchJson<T>(`${this.base}${path}`, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${this.accessToken}` },
+      provider: this.provider,
+      operation,
+    })
+  }
+}

package/src/internal/meta/meta_signature.ts

@@ -0,0 +1,22 @@
+/**
+ * Meta's `X-Hub-Signature-256` verifier — used by both WhatsApp
+ * Cloud and Messenger. The header is `sha256=<hex>` of an
+ * HMAC-SHA256 over the raw request body keyed on the App
+ * Secret. Compared in constant time to defeat timing oracles.
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+export function verifyMetaSignature(
+  rawBody: string,
+  header: string | null | undefined,
+  appSecret: string,
+): boolean {
+  if (!header) return false
+  const prefix = 'sha256='
+  if (!header.startsWith(prefix)) return false
+  const provided = header.slice(prefix.length)
+  const expected = createHmac('sha256', appSecret).update(rawBody).digest('hex')
+  if (provided.length !== expected.length) return false
+  return timingSafeEqual(Buffer.from(provided, 'hex'), Buffer.from(expected, 'hex'))
+}

package/src/internal/meta/meta_webhook_challenge.ts

@@ -0,0 +1,19 @@
+/**
+ * Meta's GET-handshake responder. Used by WhatsApp Cloud and
+ * Messenger Send API webhook verification.
+ *
+ * The receiver passes the request query params; the driver
+ * returns the challenge string to echo back when the verify
+ * token matches, or `null` to reject.
+ */
+
+export function verifyMetaChallenge(
+  params: Record<string, string | undefined>,
+  verifyToken: string,
+): string | null {
+  const mode = params['hub.mode']
+  const token = params['hub.verify_token']
+  const challenge = params['hub.challenge']
+  if (mode === 'subscribe' && token === verifyToken && challenge) return challenge
+  return null
+}

package/src/message.ts

@@ -0,0 +1,65 @@
+/**
+ * `OutgoingMessage` — the lowest-common-denominator wire shape the
+ * `InstantManager` exposes for portable sends. Apps that target
+ * multiple providers stick to these fields; apps that need
+ * provider-specific richness (LINE Flex, WhatsApp templates,
+ * Messenger generic templates) drop down to `raw` or call into the
+ * subpath driver directly.
+ *
+ * Every field is optional so the same shape can carry "just text",
+ * "text + image", "quick replies only", etc. Drivers throw
+ * `ProviderUnsupportedError` for fields they can't fulfil — apps
+ * gate on `driver.capabilities` to branch ahead of the call.
+ */
+
+export interface OutgoingMessage {
+  /** Plain-text body. Required for `send.text` calls. */
+  text?: string
+  /** Media + structured content attached to the message. */
+  attachments?: Attachment[]
+  /** Buttons rendered alongside the message (LINE quick reply, WhatsApp buttons, Messenger quick replies). */
+  quickReplies?: QuickReply[]
+  /**
+   * Provider-native message object. When set, the driver
+   * forwards it verbatim and ignores the LCD fields above.
+   * Use this when reaching for provider-specific richness
+   * (e.g. a `FlexBubble` from `@strav/instant/line`).
+   */
+  raw?: unknown
+}
+
+export type Attachment =
+  | { type: 'image'; url: string; previewUrl?: string }
+  | { type: 'video'; url: string; previewUrl?: string; durationMs?: number }
+  | { type: 'audio'; url: string; durationMs?: number }
+  | { type: 'file'; url: string; fileName?: string; sizeBytes?: number }
+  | { type: 'location'; latitude: number; longitude: number; title?: string; address?: string }
+  | { type: 'sticker'; packageId: string; stickerId: string }
+
+export interface QuickReply {
+  label: string
+  /** Action fired when the reply is tapped. */
+  action:
+    | { type: 'message'; text: string }
+    | { type: 'postback'; data: string; displayText?: string }
+    | { type: 'uri'; uri: string }
+  /** Icon shown next to the label, where the provider supports it. */
+  iconUrl?: string
+}
+
+/**
+ * `SendResult` — what every send call returns. Drivers populate
+ * `messageId` when the provider hands one back (LINE's
+ * `x-line-request-id`, WhatsApp's `messages[0].id`); some only
+ * confirm acceptance and leave it undefined.
+ */
+export interface SendResult {
+  /** Driver name (`'line'`, `'whatsapp'`, …). */
+  provider: string
+  /** Whether the upstream API accepted the send. */
+  accepted: boolean
+  /** Provider-issued reference, when one exists. */
+  messageId?: string
+  /** Raw provider response for advanced inspection. */
+  raw?: unknown
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+/**
+ * `@strav/instant` — runtime config shapes.
+ *
+ * `InstantConfig` is the `config.instant` shape apps declare in
+ * `config/instant.ts`. Multi-provider by default (apps could run
+ * one LINE bot for support, another for marketing). `providers`
+ * is keyed by app-chosen instance name; each entry carries a
+ * `driver` discriminator the framework resolves to a concrete
+ * `InstantDriver`. Apps with a single provider just register one
+ * entry.
+ *
+ * `ProviderConfig` is free-form so each adapter owns its own
+ * config shape (`LineProviderConfig` etc.) without forcing the
+ * core to know every vendor field.
+ */
+
+export interface InstantConfig {
+  /** Key into `providers`. The default routing target for unqualified `instant.*` calls. */
+  default: string
+  providers: Record<string, ProviderConfig>
+}
+
+export interface ProviderConfig {
+  /**
+   * Driver identifier — must match a name registered via
+   * `manager.extend(name, factory)` (typically by an adapter
+   * ServiceProvider).
+   */
+  driver: string
+  /** Driver-specific fields — see each adapter's `*Config`. */
+  [key: string]: unknown
+}

package/src/webhook_event.ts

@@ -0,0 +1,93 @@
+/**
+ * `WebhookEvent` — the normalized inbound event union the manager
+ * exposes to apps. Drivers convert their provider-native event
+ * shape (LINE event, WhatsApp change, Messenger entry) into one
+ * of these variants. Events the driver can't normalize map to
+ * `unknown` and surface via `raw` so apps that opt into raw
+ * handling don't lose anything.
+ *
+ * Every variant carries `provider`, `userId` (the opaque
+ * recipient identifier — LINE `userId`, WhatsApp phone, Messenger
+ * PSID), `timestamp`, and `raw` so apps can drop down when the
+ * normalized shape isn't enough.
+ */
+
+export interface WebhookEventBase {
+  /** Driver name. */
+  provider: string
+  /** Opaque user identifier from the provider. */
+  userId: string
+  /** Provider-issued event timestamp (Date). */
+  timestamp: Date
+  /** Conversation source — direct chat (`user`), group (`group`), room (`room`), etc. */
+  source: 'user' | 'group' | 'room' | 'unknown'
+  /** Group / room id when `source !== 'user'`. */
+  sourceId?: string
+  /** Reply token (LINE) or message context for short-lived reply windows. */
+  replyToken?: string
+  /** Provider-native event payload. */
+  raw: unknown
+}
+
+export interface TextMessageEvent extends WebhookEventBase {
+  type: 'message.text'
+  text: string
+  /** Provider-issued message id. */
+  messageId: string
+}
+
+export interface MediaMessageEvent extends WebhookEventBase {
+  type: 'message.image' | 'message.video' | 'message.audio' | 'message.file'
+  messageId: string
+  /** When the provider hands back content directly (vs. needing a fetch). */
+  contentUrl?: string
+}
+
+export interface LocationMessageEvent extends WebhookEventBase {
+  type: 'message.location'
+  messageId: string
+  latitude: number
+  longitude: number
+  title?: string
+  address?: string
+}
+
+export interface StickerMessageEvent extends WebhookEventBase {
+  type: 'message.sticker'
+  messageId: string
+  packageId?: string
+  stickerId?: string
+}
+
+export interface PostbackEvent extends WebhookEventBase {
+  type: 'postback'
+  data: string
+}
+
+export interface FollowEvent extends WebhookEventBase {
+  type: 'follow' | 'unfollow'
+}
+
+export interface JoinEvent extends WebhookEventBase {
+  type: 'join' | 'leave'
+}
+
+export interface BeaconEvent extends WebhookEventBase {
+  type: 'beacon'
+  beacon: { hwid: string; kind: 'enter' | 'banner' | 'stay'; dm?: string }
+}
+
+export interface UnknownEvent extends WebhookEventBase {
+  type: 'unknown'
+}
+
+export type WebhookEvent =
+  | TextMessageEvent
+  | MediaMessageEvent
+  | LocationMessageEvent
+  | StickerMessageEvent
+  | PostbackEvent
+  | FollowEvent
+  | JoinEvent
+  | BeaconEvent
+  | UnknownEvent