@strav/instant 1.0.0-alpha.42

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@strav/instant",
+  "version": "1.0.0-alpha.42",
+  "description": "Strav instant messaging — provider-agnostic abstraction for SEA messengers. Normalized OutgoingMessage + capability-flagged drivers + webhook receiver. Ships LINE (Flex / rich menus / LIFF), Telegram (inline keyboards / Web Apps), WhatsApp (interactive / Flows / templates), Messenger (templates / webview), and Zalo (ZNS / Mini App) as subpath imports.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./line": "./src/drivers/line/index.ts",
+    "./line/client": "./src/drivers/line/liff_client.ts",
+    "./telegram": "./src/drivers/telegram/index.ts",
+    "./whatsapp": "./src/drivers/whatsapp/index.ts",
+    "./whatsapp/flows": "./src/drivers/whatsapp/flows/index.ts",
+    "./messenger": "./src/drivers/messenger/index.ts",
+    "./zalo": "./src/drivers/zalo/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@line/bot-sdk": "^11.0.1",
+    "@strav/kernel": "1.0.0-alpha.42"
+  },
+  "devDependencies": {
+    "@strav/auth": "1.0.0-alpha.42",
+    "@strav/http": "1.0.0-alpha.42"
+  },
+  "peerDependencies": {
+    "@strav/auth": "1.0.0-alpha.42",
+    "@strav/http": "1.0.0-alpha.42",
+    "@types/bun": ">=1.3.14"
+  },
+  "peerDependenciesMeta": {
+    "@strav/auth": {
+      "optional": true
+    },
+    "@strav/http": {
+      "optional": true
+    }
+  }
+}

package/src/drivers/line/index.ts

@@ -0,0 +1,50 @@
+// Public API of `@strav/instant/line`.
+//
+// Subpath barrel for the LINE driver. Apps import the
+// ServiceProvider and register it in `bootstrap/providers.ts`:
+//
+// ```ts
+// import { InstantProvider } from '@strav/instant'
+// import { LineInstantProvider } from '@strav/instant/line'
+//
+// export default [InstantProvider, LineInstantProvider, ...]
+// ```
+//
+// LINE-only surfaces (`flex`, `LineRichMenu`, `LineLiff`,
+// `isBeaconEvent`) are exported here for apps that need them.
+
+export { isBeaconEvent } from './line_beacon.ts'
+export type { LineLiffConfig, LineProviderConfig } from './line_config.ts'
+export {
+  LineDriver,
+  type LineDriverOptions,
+} from './line_driver.ts'
+export {
+  type BubbleInput,
+  type FlexBox,
+  type FlexBubble,
+  type FlexButton,
+  type FlexCarousel,
+  type FlexComponent,
+  type FlexContainer,
+  type FlexImage,
+  type FlexSeparator,
+  type FlexText,
+  flex,
+} from './line_flex.ts'
+export {
+  type LiffIdTokenClaims,
+  LineLiff,
+  type VerifyIdTokenOptions,
+} from './line_liff.ts'
+export {
+  liffSignInRoute,
+  type LiffSignInRouteOptions,
+} from './liff_sign_in_route.ts'
+export { toLineMessages } from './line_message_mapper.ts'
+export { LineInstantProvider } from './line_provider.ts'
+export { LineRichMenu } from './line_rich_menu.ts'
+export {
+  parseLineWebhook,
+  verifyLineSignature,
+} from './line_webhook.ts'

package/src/drivers/line/liff_client.ts

@@ -0,0 +1,126 @@
+/**
+ * `@strav/instant/line/client` — browser-only LIFF bootstrap.
+ *
+ * Runs inside LINE's in-app webview (or an external browser when the
+ * LIFF app is opened outside LINE). Wraps the canonical handshake:
+ *
+ *   1. `liff.init({ liffId })`
+ *   2. If `!liff.isLoggedIn()` → `liff.login()` (browser navigates;
+ *      this fn throws so callers stop here)
+ *   3. `liff.getIDToken()` + `liff.getProfile()`
+ *   4. POST `{ idToken }` to the server `signInEndpoint` — wired to
+ *      `liffSignInRoute()` on the backend.
+ *
+ * The LIFF SDK itself is loaded from LINE's CDN — apps include this
+ * tag in the page that hosts the LIFF app:
+ *
+ *   <script src="https://static.line-scdn.net/liff/edge/2/sdk.js"></script>
+ *
+ * Then bundle this module via the app's frontend toolchain (Vite,
+ * esbuild, etc.) and call `initLiffSignIn(...)` at page load.
+ *
+ * This module deliberately ships zero runtime imports — it leans on
+ * the global `liff` the CDN script sets — so it bundles to a few
+ * hundred bytes.
+ */
+
+interface LiffProfile {
+  userId: string
+  displayName?: string
+  pictureUrl?: string
+  statusMessage?: string
+}
+
+interface LiffGlobal {
+  init(config: { liffId: string; withLoginOnExternalBrowser?: boolean }): Promise<void>
+  isLoggedIn(): boolean
+  login(options?: { redirectUri?: string }): void
+  getIDToken(): string | null
+  getProfile(): Promise<LiffProfile>
+  isInClient(): boolean
+}
+
+interface LiffWindow {
+  liff?: LiffGlobal
+}
+
+export interface InitLiffSignInOptions {
+  /** LIFF app id from the LINE developers console. */
+  liffId: string
+  /** Backend route bound to `liffSignInRoute()`. POST'd as JSON `{ idToken }`. */
+  signInEndpoint: string
+  /**
+   * Extra `RequestInit` merged into the sign-in POST. Default
+   * `{ credentials: 'include' }` — cookies on, so server-issued
+   * session cookies attach to subsequent requests. Override the
+   * `headers` to add CSRF tokens.
+   */
+  fetch?: RequestInit
+  /**
+   * When `true`, throw instead of redirecting to LINE login if the
+   * user isn't logged in. Rare — the LIFF default UX is to auto-
+   * redirect. Useful in tests or admin tools.
+   */
+  noAutoLogin?: boolean
+  /**
+   * Forwarded to `liff.init()` — opens an external browser when the
+   * LIFF link is tapped outside LINE. Default `false` (LINE's
+   * default; the SDK only triggers OAuth flow when needed).
+   */
+  withLoginOnExternalBrowser?: boolean
+}
+
+export interface LiffSignInResult {
+  /** The verified ID token. Apps rarely use this client-side — kept for advanced cases. */
+  idToken: string
+  /** LIFF-reported profile. Treat as advisory until the server returns success. */
+  profile: LiffProfile
+  /** The fetch Response from the sign-in POST. Apps inspect `response.ok` + parse the body. */
+  response: Response
+}
+
+export async function initLiffSignIn(
+  options: InitLiffSignInOptions,
+): Promise<LiffSignInResult> {
+  const liff = (globalThis as unknown as LiffWindow).liff
+  if (!liff) {
+    throw new Error(
+      'initLiffSignIn: window.liff is undefined. Load the LIFF SDK before calling: <script src="https://static.line-scdn.net/liff/edge/2/sdk.js"></script>',
+    )
+  }
+
+  await liff.init({
+    liffId: options.liffId,
+    ...(options.withLoginOnExternalBrowser ? { withLoginOnExternalBrowser: true } : {}),
+  })
+
+  if (!liff.isLoggedIn()) {
+    if (options.noAutoLogin) {
+      throw new Error('initLiffSignIn: user is not logged in (noAutoLogin=true).')
+    }
+    liff.login()
+    // login() navigates the browser; we throw so callers don't keep
+    // executing as if everything worked.
+    throw new Error('initLiffSignIn: redirecting to LINE login.')
+  }
+
+  const idToken = liff.getIDToken()
+  if (!idToken) {
+    throw new Error(
+      'initLiffSignIn: liff.getIDToken() returned null. The LIFF channel must have the `openid` scope.',
+    )
+  }
+
+  const profile = await liff.getProfile()
+
+  const init: RequestInit = {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    credentials: 'include',
+    ...options.fetch,
+    body: JSON.stringify({ idToken }),
+  }
+  const response = await fetch(options.signInEndpoint, init)
+
+  return { idToken, profile, response }
+}

package/src/drivers/line/liff_sign_in_route.ts

@@ -0,0 +1,112 @@
+/**
+ * `liffSignInRoute` — HTTP route handler that completes the LIFF
+ * sign-in handshake.
+ *
+ * Browser-side flow (see `@strav/instant/line/client`): the LIFF SDK
+ * runs inside LINE's webview, calls `liff.getIDToken()`, and POSTs the
+ * token to this route. The route:
+ *
+ *   1. Reads `{ idToken, nonce? }` from the JSON body.
+ *   2. Verifies the token via `LineLiff.verifyIdToken()` — signature,
+ *      audience (channel id), expiry, and the optional nonce.
+ *   3. Calls the app-provided `onSignIn(claims, ctx)` callback. Apps
+ *      do their find-or-create against the verified `claims.sub` (the
+ *      LINE user id) and return their domain `User`. Returning `null`
+ *      fails the request (401) — useful for "this LINE id isn't
+ *      allowed into the app" gating.
+ *   4. If a `guard` is provided, calls `guard.login(ctx, user)` so
+ *      subsequent requests are authenticated.
+ *   5. Returns `{ ok: true, claims }`.
+ *
+ * Apps that don't use `@strav/auth` skip the `guard` option and read
+ * the response's `claims` to issue their own session.
+ *
+ * Errors are mapped to HTTP status:
+ *   - Missing / non-JSON body → 400
+ *   - Missing `idToken` → 400
+ *   - LIFF verification failure → 401
+ *   - `onSignIn` returns null → 401
+ *   - `onSignIn` throws → re-raised (framework error handler decides
+ *     the response)
+ */
+
+import type { Authenticatable, Guard } from '@strav/auth'
+import type { HttpContext } from '@strav/http'
+import { InstantProviderError } from '../../errors.ts'
+import type { LineLiff, LiffIdTokenClaims, VerifyIdTokenOptions } from './line_liff.ts'
+
+export interface LiffSignInRouteOptions<U extends Authenticatable = Authenticatable> {
+  /** Configured LineLiff helper (its `channelId` is the LIFF channel id). */
+  liff: LineLiff
+  /**
+   * App-provided hook — receives the verified claims + request
+   * context, returns the domain user to sign in. Return `null` to
+   * reject the request (the route returns 401). Throw to bubble up
+   * to the framework's error handler.
+   */
+  onSignIn: (
+    claims: LiffIdTokenClaims,
+    ctx: HttpContext,
+  ) => Promise<U | null> | U | null
+  /** Optional auth guard. When set, the route calls `guard.login(ctx, user)` after `onSignIn`. */
+  guard?: Guard<U>
+  /** Forwarded to `liff.verifyIdToken(idToken, options)` (e.g. `userId` match). The `nonce` is read from the request body when present. */
+  verifyOptions?: Omit<VerifyIdTokenOptions, 'nonce'>
+}
+
+interface SignInRequestBody {
+  idToken?: unknown
+  nonce?: unknown
+}
+
+export function liffSignInRoute<U extends Authenticatable = Authenticatable>(
+  options: LiffSignInRouteOptions<U>,
+): (ctx: HttpContext) => Promise<Response> {
+  return async (ctx: HttpContext): Promise<Response> => {
+    let body: SignInRequestBody
+    try {
+      body = (await ctx.request.raw.json()) as SignInRequestBody
+    } catch {
+      return ctx.response.json({ error: 'Request body must be JSON.' }, { status: 400 })
+    }
+
+    const idToken = typeof body.idToken === 'string' ? body.idToken : null
+    if (!idToken) {
+      return ctx.response.json(
+        { error: 'Missing or non-string `idToken` field.' },
+        { status: 400 },
+      )
+    }
+    const nonce = typeof body.nonce === 'string' ? body.nonce : undefined
+
+    let claims: LiffIdTokenClaims
+    try {
+      claims = await options.liff.verifyIdToken(idToken, {
+        ...(options.verifyOptions ?? {}),
+        ...(nonce ? { nonce } : {}),
+      })
+    } catch (cause) {
+      if (cause instanceof InstantProviderError) {
+        return ctx.response.json(
+          { error: cause.message, code: cause.code },
+          { status: 401 },
+        )
+      }
+      throw cause
+    }
+
+    const user = await options.onSignIn(claims, ctx)
+    if (!user) {
+      return ctx.response.json(
+        { error: 'Sign-in rejected for this LINE identity.' },
+        { status: 401 },
+      )
+    }
+
+    if (options.guard) {
+      await options.guard.login(ctx, user)
+    }
+
+    return ctx.response.json({ ok: true, claims })
+  }
+}

package/src/drivers/line/line_beacon.ts

@@ -0,0 +1,14 @@
+/**
+ * Beacon event type-guard helpers.
+ *
+ * Beacons are LINE-only. The normalized `WebhookEvent` already
+ * carries beacon payloads in the `BeaconEvent` variant; this
+ * module just exposes a tiny helper so apps don't repeat the
+ * discriminator check.
+ */
+
+import type { BeaconEvent, WebhookEvent } from '../../webhook_event.ts'
+
+export function isBeaconEvent(event: WebhookEvent): event is BeaconEvent {
+  return event.type === 'beacon'
+}

package/src/drivers/line/line_config.ts

@@ -0,0 +1,55 @@
+/**
+ * LINE-specific provider config.
+ *
+ * LINE splits the bot surface across two DIFFERENT channels in the
+ * Developers Console; this config makes the split explicit so
+ * apps don't accidentally point one channel's credentials at the
+ * other endpoint.
+ *
+ *   1. **Messaging API channel.** Issues `channelAccessToken` +
+ *      `channelSecret`. Authenticates push / reply / multicast /
+ *      broadcast / rich-menu calls, and signs the
+ *      `x-line-signature` webhook header.
+ *
+ *   2. **LINE Login channel.** A separate channel that LIFF apps
+ *      are bound to. The `aud` claim on a LIFF ID token is THIS
+ *      channel's id — not the Messaging channel's id. The
+ *      `/oauth2/v2.1/verify` endpoint rejects tokens whose `aud`
+ *      doesn't match the `client_id` it receives.
+ *
+ * Apps that don't use LIFF can omit `liff` entirely. Apps that
+ * use LIFF must set `liff.channelId` to the **LINE Login channel
+ * id** — copying the Messaging channel id here is the single most
+ * common misconfiguration and will fail every verify call with an
+ * audience mismatch.
+ */
+
+import type { ProviderConfig } from '../../types.ts'
+
+export interface LineProviderConfig extends ProviderConfig {
+  driver: 'line'
+  /** Messaging API channel access token. Authenticates send / push / reply / broadcast / rich-menu calls. */
+  channelAccessToken: string
+  /** Messaging API channel secret. HMAC-SHA256 key for `x-line-signature` webhook verification. */
+  channelSecret: string
+  /**
+   * LIFF / LINE Login channel — only required if the app uses
+   * LIFF. The `channelId` here MUST be the LINE Login channel id
+   * that hosts the LIFF app, NOT the Messaging API channel id.
+   */
+  liff?: LineLiffConfig
+  /** Override the Messaging API base URL (defaults to `https://api.line.me`). Useful in tests. */
+  apiBaseURL?: string
+  /** Override the data API base URL (defaults to `https://api-data.line.me`). Useful in tests. */
+  dataApiBaseURL?: string
+}
+
+export interface LineLiffConfig {
+  /**
+   * LINE Login channel id (numeric string) — the `aud` claim on
+   * every LIFF-issued ID token. Find it in the LINE Developers
+   * Console under the LINE Login channel's "Basic settings"
+   * tab, NOT the Messaging API channel.
+   */
+  channelId: string
+}

package/src/drivers/line/line_driver.ts

@@ -0,0 +1,202 @@
+/**
+ * `LineDriver` — `InstantDriver` for the LINE Messaging API.
+ *
+ * Wraps `@line/bot-sdk`'s `LineBotClient` for send / reply / push
+ * / multicast / broadcast / profile. Webhook signature
+ * verification and event parsing live in `line_webhook.ts`; the
+ * driver delegates to those.
+ *
+ * Capability declarations match what LINE supports natively. LIFF
+ * (`liff`), Flex (`send.flex`), rich menus (`richMenu`), and
+ * beacons (`beacon`) are all included — apps reach the matching
+ * helpers via the subpath barrel:
+ *
+ *   import { LineDriver, flex, LineLiff, LineRichMenu } from '@strav/instant/line'
+ */
+
+import { LineBotClient, type messagingApi } from '@line/bot-sdk'
+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 type { LineProviderConfig } from './line_config.ts'
+import { LineLiff } from './line_liff.ts'
+import { toLineMessages } from './line_message_mapper.ts'
+import { LineRichMenu } from './line_rich_menu.ts'
+import { parseLineWebhook, verifyLineSignature } from './line_webhook.ts'
+
+const DEFAULT_CAPABILITIES: ReadonlySet<InstantCapability> = new Set<InstantCapability>([
+  'send.text',
+  'send.image',
+  'send.video',
+  'send.audio',
+  'send.location',
+  'send.sticker',
+  'send.quickReplies',
+  'send.flex',
+  'send.template',
+  'reply',
+  'push',
+  'multicast',
+  'broadcast',
+  'profile',
+  'richMenu',
+  'beacon',
+  'liff',
+  'webhook.signature',
+  'webhook.parse',
+])
+
+export interface LineDriverOptions {
+  instanceName: string
+  config: LineProviderConfig
+  /** Inject a pre-built client (tests / mocks). */
+  client?: LineBotClient
+}
+
+export class LineDriver implements InstantDriver {
+  readonly name = 'line'
+  readonly instanceName: string
+  readonly capabilities = DEFAULT_CAPABILITIES
+  readonly client: LineBotClient
+  readonly webhook: WebhookOps
+
+  /** Lazy LIFF helper — constructed on first access since not every app uses LIFF. */
+  private _liff: LineLiff | undefined
+  /** Lazy rich-menu helper. */
+  private _richMenu: LineRichMenu | undefined
+
+  constructor(options: LineDriverOptions) {
+    const { instanceName, config } = options
+    if (!config.channelAccessToken) {
+      throw new InstantProviderError(
+        `LineDriver: \`channelAccessToken\` is required for provider "${instanceName}".`,
+        { provider: 'line', operation: 'init', status: 500 },
+      )
+    }
+    if (!config.channelSecret) {
+      throw new InstantProviderError(
+        `LineDriver: \`channelSecret\` is required for provider "${instanceName}".`,
+        { provider: 'line', operation: 'init', status: 500 },
+      )
+    }
+    this.instanceName = instanceName
+    this.client =
+      options.client ??
+      LineBotClient.fromChannelAccessToken({
+        channelAccessToken: config.channelAccessToken,
+        ...(config.apiBaseURL ? { apiBaseURL: config.apiBaseURL } : {}),
+        ...(config.dataApiBaseURL ? { dataApiBaseURL: config.dataApiBaseURL } : {}),
+      })
+    const channelSecret = config.channelSecret
+    const liffChannelId = config.liff?.channelId
+    this.webhook = {
+      verifySignature: (rawBody, signature) =>
+        verifyLineSignature(rawBody, signature, channelSecret),
+      parse: (rawBody) => parseLineWebhook(rawBody),
+    }
+    if (liffChannelId) this._liff = new LineLiff(liffChannelId)
+  }
+
+  // ─── Send / push / reply / multicast / broadcast ─────────────────────
+
+  async send(to: string, message: OutgoingMessage): Promise<SendResult> {
+    return this.push(to, message)
+  }
+
+  async push(to: string, message: OutgoingMessage): Promise<SendResult> {
+    return this.guard('push', async () => {
+      const request: messagingApi.PushMessageRequest = {
+        to,
+        messages: toLineMessages(message),
+      }
+      const response = await this.client.pushMessage(request)
+      return {
+        provider: 'line',
+        accepted: true,
+        ...((response as { sentMessages?: Array<{ id?: string }> })?.sentMessages?.[0]?.id
+          ? {
+              messageId: (response as { sentMessages: Array<{ id?: string }> }).sentMessages[0]!.id,
+            }
+          : {}),
+        raw: response,
+      }
+    })
+  }
+
+  async reply(replyToken: string, message: OutgoingMessage): Promise<SendResult> {
+    return this.guard('reply', async () => {
+      const request: messagingApi.ReplyMessageRequest = {
+        replyToken,
+        messages: toLineMessages(message),
+      }
+      const response = await this.client.replyMessage(request)
+      return { provider: 'line', accepted: true, raw: response }
+    })
+  }
+
+  async multicast(to: readonly string[], message: OutgoingMessage): Promise<SendResult> {
+    return this.guard('multicast', async () => {
+      const request: messagingApi.MulticastRequest = {
+        to: [...to],
+        messages: toLineMessages(message),
+      }
+      const response = await this.client.multicast(request)
+      return { provider: 'line', accepted: true, raw: response }
+    })
+  }
+
+  async broadcast(message: OutgoingMessage): Promise<SendResult> {
+    return this.guard('broadcast', async () => {
+      const request: messagingApi.BroadcastRequest = {
+        messages: toLineMessages(message),
+      }
+      const response = await this.client.broadcast(request)
+      return { provider: 'line', accepted: true, raw: response }
+    })
+  }
+
+  async profile(userId: string): Promise<UserProfile> {
+    return this.guard('profile', async () => {
+      const r = await this.client.getProfile(userId)
+      return {
+        userId: r.userId,
+        ...(r.displayName ? { displayName: r.displayName } : {}),
+        ...(r.pictureUrl ? { pictureUrl: r.pictureUrl } : {}),
+        ...(r.statusMessage ? { statusMessage: r.statusMessage } : {}),
+        ...(r.language ? { language: r.language } : {}),
+        raw: r,
+      }
+    })
+  }
+
+  // ─── LINE-specific surfaces ──────────────────────────────────────────
+
+  get liff(): LineLiff {
+    if (!this._liff) {
+      throw new InstantProviderError(
+        'LineDriver: `liff.channelId` is not configured — set `config.liff.channelId` to the LINE Login channel id that hosts the LIFF app (NOT the Messaging API channel id).',
+        { provider: 'line', operation: 'liff', status: 500 },
+      )
+    }
+    return this._liff
+  }
+
+  get richMenu(): LineRichMenu {
+    if (!this._richMenu) this._richMenu = new LineRichMenu(this.client)
+    return this._richMenu
+  }
+
+  private async guard<T>(operation: string, run: () => Promise<T>): Promise<T> {
+    try {
+      return await run()
+    } catch (cause) {
+      if (cause instanceof InstantProviderError) throw cause
+      throw new InstantProviderError(`LINE \`${operation}\` failed.`, {
+        provider: 'line',
+        operation,
+        cause,
+      })
+    }
+  }
+}