@strav/instant 1.0.0-alpha.42

package/src/drivers/line/line_flex.ts

@@ -0,0 +1,117 @@
+/**
+ * `flex` — typed builder for LINE Flex Messages.
+ *
+ * Flex JSON is rich enough that hand-writing it gets painful fast.
+ * The builders re-export the SDK's underlying types via
+ * pass-through functions that fill in the `type` discriminator and
+ * narrow option bags. The output is plain JSON assignable to
+ * `FlexContainer` / `FlexComponent`, which the driver wraps in a
+ * `FlexMessage` when sending.
+ *
+ * Apps that need a shape not covered here (very rare — there are
+ * only ~9 components) hand-write the JSON; everything composes.
+ */
+
+import type { messagingApi } from '@line/bot-sdk'
+
+type FlexBubble = messagingApi.FlexBubble
+type FlexCarousel = messagingApi.FlexCarousel
+type FlexBox = messagingApi.FlexBox
+type FlexText = messagingApi.FlexText
+type FlexButton = messagingApi.FlexButton
+type FlexImage = messagingApi.FlexImage
+type FlexSeparator = messagingApi.FlexSeparator
+type FlexComponent = messagingApi.FlexComponent
+type FlexContainer = messagingApi.FlexContainer
+type Action = messagingApi.Action
+
+export interface BubbleInput {
+  size?: FlexBubble['size']
+  direction?: FlexBubble['direction']
+  header?: FlexBox
+  hero?: FlexImage | FlexBox
+  body?: FlexBox
+  footer?: FlexBox
+  styles?: FlexBubble['styles']
+}
+
+function bubble(input: BubbleInput): FlexBubble {
+  return { type: 'bubble', ...input } as FlexBubble
+}
+
+function carousel(bubbles: FlexBubble[]): FlexCarousel {
+  return { type: 'carousel', contents: bubbles }
+}
+
+function box(
+  layout: FlexBox['layout'],
+  contents: FlexComponent[],
+  options: Omit<FlexBox, 'type' | 'layout' | 'contents'> = {},
+): FlexBox {
+  return { type: 'box', layout, contents, ...options }
+}
+
+function text(value: string, options: Omit<FlexText, 'type' | 'text'> = {}): FlexText {
+  return { type: 'text', text: value, ...options }
+}
+
+function button(options: Omit<FlexButton, 'type'>): FlexButton {
+  return { type: 'button', ...options }
+}
+
+function image(url: string, options: Omit<FlexImage, 'type' | 'url'> = {}): FlexImage {
+  return { type: 'image', url, ...options }
+}
+
+function separator(options: Omit<FlexSeparator, 'type'> = {}): FlexSeparator {
+  return { type: 'separator', ...options }
+}
+
+function messageAction(label: string, text: string): Action {
+  return { type: 'message', label, text }
+}
+
+function postbackAction(
+  label: string,
+  data: string,
+  options: { displayText?: string } = {},
+): Action {
+  return { type: 'postback', label, data, ...options }
+}
+
+function uriAction(label: string, uri: string): Action {
+  return { type: 'uri', label, uri }
+}
+
+/**
+ * Flex builder facade. Importable as a namespace:
+ *
+ *   import { flex } from '@strav/instant/line'
+ *   const bubble = flex.bubble({ body: flex.box('vertical', [flex.text('Hi')]) })
+ */
+export const flex = {
+  bubble,
+  carousel,
+  box,
+  text,
+  button,
+  image,
+  separator,
+  action: {
+    message: messageAction,
+    postback: postbackAction,
+    uri: uriAction,
+  },
+}
+
+export type {
+  FlexBox,
+  FlexBubble,
+  FlexButton,
+  FlexCarousel,
+  FlexComponent,
+  FlexContainer,
+  FlexImage,
+  FlexSeparator,
+  FlexText,
+}

package/src/drivers/line/line_liff.ts

@@ -0,0 +1,102 @@
+/**
+ * LIFF ID-token verification.
+ *
+ * LIFF apps run client-side inside LINE's in-app webview. The
+ * frontend obtains an ID token via `liff.getIDToken()` and posts it
+ * to the backend; the backend MUST verify the token with LINE
+ * (signature, audience, expiry) before trusting any claim from it.
+ *
+ * `verifyIdToken` POSTs to `https://api.line.me/oauth2/v2.1/verify`
+ * with the channel id as `client_id`. LINE returns the decoded
+ * claims (`sub`, `name`, `picture`, `email` when the user
+ * consented to the email scope) when the token is valid; we throw
+ * `InstantProviderError` otherwise.
+ *
+ * Never trust a userId received directly from a LIFF frontend —
+ * always validate via this helper first.
+ */
+
+import { InstantProviderError } from '../../errors.ts'
+
+const LINE_VERIFY_ENDPOINT = 'https://api.line.me/oauth2/v2.1/verify'
+
+export interface LiffIdTokenClaims {
+  /** LINE user id (`sub` claim — same as `userId` from Messaging API). */
+  sub: string
+  /** Display name. Always present when the token is valid. */
+  name?: string
+  /** Profile picture URL. Present when the user has one. */
+  picture?: string
+  /** Email — only present when the channel has the `email` scope and the user consented. */
+  email?: string
+  /** Audience claim — should equal the channel id we passed. */
+  aud: string
+  /** Issuer (`https://access.line.me`). */
+  iss: string
+  /** Expiry (seconds since epoch). */
+  exp: number
+  /** Issued-at (seconds since epoch). */
+  iat: number
+  /** Raw claims object from LINE — keep the rest for advanced cases. */
+  raw: Record<string, unknown>
+}
+
+export interface VerifyIdTokenOptions {
+  /** Required nonce match — LINE's response must echo this value. */
+  nonce?: string
+  /** Required user id match — convenience check on top of `sub`. */
+  userId?: string
+  /** Override the verify endpoint (tests). */
+  endpoint?: string
+}
+
+export class LineLiff {
+  constructor(private readonly channelId: string) {
+    if (!channelId) {
+      throw new InstantProviderError(
+        'LineLiff: `channelId` is required for ID-token verification.',
+        {
+          provider: 'line',
+          operation: 'liff.verifyIdToken',
+          status: 500,
+        },
+      )
+    }
+  }
+
+  async verifyIdToken(
+    idToken: string,
+    options: VerifyIdTokenOptions = {},
+  ): Promise<LiffIdTokenClaims> {
+    const body = new URLSearchParams({ id_token: idToken, client_id: this.channelId })
+    if (options.nonce) body.set('nonce', options.nonce)
+    if (options.userId) body.set('user_id', options.userId)
+
+    const response = await fetch(options.endpoint ?? LINE_VERIFY_ENDPOINT, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+    })
+
+    const payload = (await response.json().catch(() => null)) as Record<string, unknown> | null
+    if (!response.ok || !payload) {
+      throw new InstantProviderError('LineLiff: ID-token verification failed.', {
+        provider: 'line',
+        operation: 'liff.verifyIdToken',
+        status: response.status,
+        context: { response: payload },
+      })
+    }
+    return {
+      sub: String(payload.sub ?? ''),
+      ...(payload.name ? { name: String(payload.name) } : {}),
+      ...(payload.picture ? { picture: String(payload.picture) } : {}),
+      ...(payload.email ? { email: String(payload.email) } : {}),
+      aud: String(payload.aud ?? ''),
+      iss: String(payload.iss ?? ''),
+      exp: Number(payload.exp ?? 0),
+      iat: Number(payload.iat ?? 0),
+      raw: payload,
+    }
+  }
+}

package/src/drivers/line/line_message_mapper.ts

@@ -0,0 +1,118 @@
+/**
+ * Map the framework's LCD `OutgoingMessage` shape onto LINE's
+ * `Message` JSON.
+ *
+ * LINE accepts 1-5 `Message` objects per push / reply / multicast
+ * call; the mapper expands a single `OutgoingMessage` into the
+ * matching number of LINE messages: one for text, one per
+ * attachment, plus quick replies attached to the LAST message
+ * (LINE only honours `quickReply` on the last item of a batch).
+ *
+ * `raw` is a passthrough — apps that need a shape outside the LCD
+ * (Flex bubbles built by `flex.*`, template messages, imagemaps)
+ * set `message.raw` to the LINE JSON and it goes through verbatim.
+ * When `raw` is set, the LCD fields are ignored.
+ */
+
+import type { messagingApi } from '@line/bot-sdk'
+import { InstantProviderError } from '../../errors.ts'
+import type { Attachment, OutgoingMessage, QuickReply } from '../../message.ts'
+
+type LineMessage = messagingApi.Message
+type LineQuickReply = messagingApi.QuickReply
+type LineAction = messagingApi.Action
+
+export function toLineMessages(message: OutgoingMessage): LineMessage[] {
+  if (message.raw !== undefined) {
+    const raw = message.raw as LineMessage | LineMessage[]
+    return Array.isArray(raw) ? raw : [raw]
+  }
+
+  const messages: LineMessage[] = []
+
+  if (message.text) {
+    messages.push({ type: 'text', text: message.text })
+  }
+
+  if (message.attachments) {
+    for (const a of message.attachments) {
+      messages.push(toLineAttachment(a))
+    }
+  }
+
+  if (messages.length === 0) {
+    throw new InstantProviderError(
+      'LineDriver: cannot send an empty message — set `text`, `attachments`, or `raw`.',
+      { provider: 'line', operation: 'send', status: 400 },
+    )
+  }
+
+  if (message.quickReplies && message.quickReplies.length > 0) {
+    const last = messages[messages.length - 1] as LineMessage & { quickReply?: LineQuickReply }
+    last.quickReply = toLineQuickReply(message.quickReplies)
+  }
+
+  return messages
+}
+
+function toLineAttachment(a: Attachment): LineMessage {
+  switch (a.type) {
+    case 'image':
+      return {
+        type: 'image',
+        originalContentUrl: a.url,
+        previewImageUrl: a.previewUrl ?? a.url,
+      }
+    case 'video':
+      return {
+        type: 'video',
+        originalContentUrl: a.url,
+        previewImageUrl: a.previewUrl ?? a.url,
+      }
+    case 'audio':
+      return {
+        type: 'audio',
+        originalContentUrl: a.url,
+        duration: a.durationMs ?? 0,
+      }
+    case 'file':
+      // LINE has no first-class "file" message — fall back to a text link.
+      return { type: 'text', text: a.fileName ? `${a.fileName}\n${a.url}` : a.url }
+    case 'location':
+      return {
+        type: 'location',
+        title: a.title ?? 'Location',
+        address: a.address ?? '',
+        latitude: a.latitude,
+        longitude: a.longitude,
+      }
+    case 'sticker':
+      return { type: 'sticker', packageId: a.packageId, stickerId: a.stickerId }
+  }
+}
+
+function toLineQuickReply(replies: readonly QuickReply[]): LineQuickReply {
+  return {
+    items: replies.slice(0, 13).map((r) => ({
+      type: 'action',
+      ...(r.iconUrl ? { imageUrl: r.iconUrl } : {}),
+      action: toLineAction(r.label, r.action),
+    })),
+  }
+}
+
+function toLineAction(label: string, action: QuickReply['action']): LineAction {
+  switch (action.type) {
+    case 'message':
+      return { type: 'message', label, text: action.text }
+    case 'postback':
+      return {
+        type: 'postback',
+        label,
+        data: action.data,
+        ...(action.displayText ? { displayText: action.displayText } : {}),
+      }
+    case 'uri':
+      return { type: 'uri', label, uri: action.uri }
+  }
+}

package/src/drivers/line/line_provider.ts

@@ -0,0 +1,33 @@
+/**
+ * `LineInstantProvider` — `ServiceProvider` that registers the
+ * LINE driver factory on the `InstantManager`.
+ *
+ * Apps list this AFTER `InstantProvider` in
+ * `bootstrap/providers.ts`. Driver instances construct lazily on
+ * first `instant.use(name)` call.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { InstantConfigError } from '../../errors.ts'
+import { InstantManager } from '../../instant_manager.ts'
+import type { LineProviderConfig } from './line_config.ts'
+import { LineDriver } from './line_driver.ts'
+
+export class LineInstantProvider extends ServiceProvider {
+  override readonly name = 'instant-line'
+  override readonly dependencies = ['instant']
+
+  override register(app: Application): void {
+    const manager = app.resolve(InstantManager)
+    manager.extend('line', ({ instanceName, config }) => {
+      const cfg = config as LineProviderConfig
+      if (!cfg.channelAccessToken || !cfg.channelSecret) {
+        throw new InstantConfigError(
+          `LineInstantProvider: \`channelAccessToken\` and \`channelSecret\` are required for provider "${instanceName}".`,
+          { context: { instanceName } },
+        )
+      }
+      return new LineDriver({ instanceName, config: cfg })
+    })
+  }
+}

package/src/drivers/line/line_rich_menu.ts

@@ -0,0 +1,68 @@
+/**
+ * LINE rich-menu CRUD wrappers.
+ *
+ * Rich menus are persistent image-based menu bars at the bottom of
+ * the LINE chat UI. Each menu is created with a JSON definition
+ * (size, tappable areas, actions), then an image is uploaded for
+ * it, and finally it's either set as the default menu or linked
+ * to specific users.
+ *
+ * Wraps `@line/bot-sdk`'s `LineBotClient`. Apps that need narrower
+ * surfaces (alias management, bulk linking) call into the client
+ * directly via `driver.client`.
+ */
+
+import type { LineBotClient, messagingApi } from '@line/bot-sdk'
+import { InstantProviderError } from '../../errors.ts'
+
+export class LineRichMenu {
+  constructor(private readonly client: LineBotClient) {}
+
+  create(input: messagingApi.RichMenuRequest): Promise<string> {
+    return this.guard('richMenu.create', () =>
+      this.client.createRichMenu(input).then((r) => r.richMenuId),
+    )
+  }
+
+  delete(richMenuId: string): Promise<void> {
+    return this.guard('richMenu.delete', () =>
+      this.client.deleteRichMenu(richMenuId).then(() => undefined),
+    )
+  }
+
+  setImage(richMenuId: string, image: Blob): Promise<void> {
+    return this.guard('richMenu.setImage', () =>
+      this.client.setRichMenuImage(richMenuId, image).then(() => undefined),
+    )
+  }
+
+  setDefault(richMenuId: string): Promise<void> {
+    return this.guard('richMenu.setDefault', () =>
+      this.client.setDefaultRichMenu(richMenuId).then(() => undefined),
+    )
+  }
+
+  linkToUser(userId: string, richMenuId: string): Promise<void> {
+    return this.guard('richMenu.linkToUser', () =>
+      this.client.linkRichMenuIdToUser(userId, richMenuId).then(() => undefined),
+    )
+  }
+
+  unlinkFromUser(userId: string): Promise<void> {
+    return this.guard('richMenu.unlinkFromUser', () =>
+      this.client.unlinkRichMenuIdFromUser(userId).then(() => undefined),
+    )
+  }
+
+  private async guard<T>(operation: string, run: () => Promise<T>): Promise<T> {
+    try {
+      return await run()
+    } catch (cause) {
+      throw new InstantProviderError(`LINE \`${operation}\` failed.`, {
+        provider: 'line',
+        operation,
+        cause,
+      })
+    }
+  }
+}

package/src/drivers/line/line_webhook.ts

@@ -0,0 +1,168 @@
+/**
+ * LINE webhook helpers — signature verification + event parsing
+ * into the framework's normalized `WebhookEvent` union.
+ *
+ * Signature verification uses `@line/bot-sdk`'s `validateSignature`
+ * (HMAC-SHA256 of the raw body against the channel secret,
+ * base64-encoded, constant-time compared against the
+ * `x-line-signature` header).
+ *
+ * Parsing turns each `events[]` entry from the LINE callback body
+ * into one normalized `WebhookEvent`. Variants the framework
+ * doesn't model (membership, video play complete, module attach,
+ * etc.) map to `{ type: 'unknown', raw }` so apps that want them
+ * can still reach the original payload via `event.raw`.
+ */
+
+import { type webhook as lineWebhook, validateSignature } from '@line/bot-sdk'
+import type {
+  BeaconEvent,
+  FollowEvent,
+  JoinEvent,
+  LocationMessageEvent,
+  MediaMessageEvent,
+  PostbackEvent,
+  StickerMessageEvent,
+  TextMessageEvent,
+  UnknownEvent,
+  WebhookEvent,
+  WebhookEventBase,
+} from '../../webhook_event.ts'
+
+type LineSource = lineWebhook.Source
+type LineEvent = lineWebhook.Event
+
+export function verifyLineSignature(
+  rawBody: string,
+  signature: string | null | undefined,
+  channelSecret: string,
+): boolean {
+  if (!signature) return false
+  try {
+    return validateSignature(rawBody, channelSecret, signature)
+  } catch {
+    return false
+  }
+}
+
+export function parseLineWebhook(rawBody: string): WebhookEvent[] {
+  const callback = JSON.parse(rawBody) as lineWebhook.CallbackRequest
+  if (!callback?.events || !Array.isArray(callback.events)) return []
+  return callback.events.map(toWebhookEvent)
+}
+
+function toWebhookEvent(event: LineEvent): WebhookEvent {
+  const base = buildBase(event)
+
+  switch (event.type) {
+    case 'message': {
+      const message = event.message
+      switch (message.type) {
+        case 'text':
+          return {
+            ...base,
+            type: 'message.text',
+            messageId: message.id,
+            text: message.text,
+          } satisfies TextMessageEvent
+        case 'image':
+        case 'video':
+        case 'audio':
+        case 'file': {
+          const media: MediaMessageEvent = {
+            ...base,
+            type: `message.${message.type}` as MediaMessageEvent['type'],
+            messageId: message.id,
+          }
+          return media
+        }
+        case 'location':
+          return {
+            ...base,
+            type: 'message.location',
+            messageId: message.id,
+            latitude: message.latitude,
+            longitude: message.longitude,
+            ...(message.title ? { title: message.title } : {}),
+            ...(message.address ? { address: message.address } : {}),
+          } satisfies LocationMessageEvent
+        case 'sticker':
+          return {
+            ...base,
+            type: 'message.sticker',
+            messageId: message.id,
+            packageId: message.packageId,
+            stickerId: message.stickerId,
+          } satisfies StickerMessageEvent
+        default:
+          return { ...base, type: 'unknown' } satisfies UnknownEvent
+      }
+    }
+    case 'postback':
+      return {
+        ...base,
+        type: 'postback',
+        data: event.postback.data,
+      } satisfies PostbackEvent
+    case 'follow':
+      return { ...base, type: 'follow' } satisfies FollowEvent
+    case 'unfollow':
+      return { ...base, type: 'unfollow' } satisfies FollowEvent
+    case 'join':
+      return { ...base, type: 'join' } satisfies JoinEvent
+    case 'leave':
+      return { ...base, type: 'leave' } satisfies JoinEvent
+    case 'beacon':
+      return {
+        ...base,
+        type: 'beacon',
+        beacon: {
+          hwid: event.beacon.hwid,
+          kind: event.beacon.type as BeaconEvent['beacon']['kind'],
+          ...(event.beacon.dm ? { dm: event.beacon.dm } : {}),
+        },
+      } satisfies BeaconEvent
+    default:
+      return { ...base, type: 'unknown' } satisfies UnknownEvent
+  }
+}
+
+function buildBase(event: LineEvent): WebhookEventBase {
+  const { userId, kind, sourceId } = readSource(event.source)
+  const replyToken = (event as { replyToken?: string }).replyToken
+  return {
+    provider: 'line',
+    userId,
+    timestamp: new Date(event.timestamp),
+    source: kind,
+    ...(sourceId ? { sourceId } : {}),
+    ...(replyToken ? { replyToken } : {}),
+    raw: event,
+  }
+}
+
+function readSource(source: LineSource | undefined): {
+  userId: string
+  kind: WebhookEventBase['source']
+  sourceId?: string
+} {
+  if (!source) return { userId: '', kind: 'unknown' }
+  switch (source.type) {
+    case 'user':
+      return { userId: source.userId ?? '', kind: 'user' }
+    case 'group':
+      return {
+        userId: source.userId ?? '',
+        kind: 'group',
+        sourceId: source.groupId,
+      }
+    case 'room':
+      return {
+        userId: source.userId ?? '',
+        kind: 'room',
+        sourceId: source.roomId,
+      }
+    default:
+      return { userId: '', kind: 'unknown' }
+  }
+}

package/src/drivers/messenger/index.ts

@@ -0,0 +1,16 @@
+// Public API of `@strav/instant/messenger`.
+
+export type { MessengerProviderConfig } from './messenger_config.ts'
+export { MessengerDriver, type MessengerDriverOptions } from './messenger_driver.ts'
+export { toMessengerPayload } from './messenger_message_mapper.ts'
+export {
+  MessengerBotProfile,
+  type PersistentMenuEntry,
+  type PersistentMenuItem,
+} from './messenger_profile.ts'
+export { MessengerInstantProvider } from './messenger_provider.ts'
+export {
+  parseMessengerWebhook,
+  verifyMessengerChallenge,
+  verifyMessengerSignature,
+} from './messenger_webhook.ts'

package/src/drivers/messenger/messenger_config.ts

@@ -0,0 +1,20 @@
+/**
+ * `MessengerProviderConfig` — config shape consumed by
+ * `MessengerInstantProvider`.
+ *
+ * Distinct from the WhatsApp Cloud config even though both
+ * use Meta's Graph: Messenger is page-scoped (`pageId` +
+ * `pageAccessToken`), WhatsApp is WABA-scoped.
+ */
+
+import type { ProviderConfig } from '../../types.ts'
+
+export interface MessengerProviderConfig extends ProviderConfig {
+  driver: 'messenger'
+  pageId: string
+  pageAccessToken: string
+  appSecret: string
+  verifyToken: string
+  /** Defaults to `v20.0`. */
+  apiVersion?: string
+}