@strav/notification 1.0.0-alpha.33 → 1.0.0-alpha.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/notification",
-  "version": "1.0.0-alpha.33",
+  "version": "1.0.0-alpha.35",
   "description": "Strav multi-channel notifications — NotificationManager fan-out across channel drivers (mail / database / log / webhook / broadcast / discord / sse). Manager+drivers shape; new channels register via `manager.extend(name, factory)`.",
   "type": "module",
   "main": "./src/index.ts",
@@ -13,6 +13,7 @@
     "./webhook": "./src/drivers/webhook/index.ts",
     "./broadcast": "./src/drivers/broadcast/index.ts",
     "./discord": "./src/drivers/discord/index.ts",
+    "./line": "./src/drivers/line/index.ts",
     "./sse": "./src/drivers/sse/index.ts",
     "./tenanted": "./src/drivers/database/tenanted/index.ts"
   },
@@ -27,19 +28,21 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/kernel": "1.0.0-alpha.33"
+    "@strav/kernel": "1.0.0-alpha.35"
   },
   "devDependencies": {
-    "@strav/broadcast": "1.0.0-alpha.33",
-    "@strav/database": "1.0.0-alpha.33",
-    "@strav/http": "1.0.0-alpha.33",
-    "@strav/mail": "1.0.0-alpha.33"
+    "@strav/broadcast": "1.0.0-alpha.35",
+    "@strav/database": "1.0.0-alpha.35",
+    "@strav/http": "1.0.0-alpha.35",
+    "@strav/instant": "1.0.0-alpha.35",
+    "@strav/mail": "1.0.0-alpha.35"
   },
   "peerDependencies": {
-    "@strav/broadcast": "1.0.0-alpha.33",
-    "@strav/database": "1.0.0-alpha.33",
-    "@strav/http": "1.0.0-alpha.33",
-    "@strav/mail": "1.0.0-alpha.33",
+    "@strav/broadcast": "1.0.0-alpha.35",
+    "@strav/database": "1.0.0-alpha.35",
+    "@strav/http": "1.0.0-alpha.35",
+    "@strav/instant": "1.0.0-alpha.35",
+    "@strav/mail": "1.0.0-alpha.35",
     "@types/bun": ">=1.3.14"
   },
   "peerDependenciesMeta": {
@@ -52,6 +55,9 @@
     "@strav/http": {
       "optional": true
     },
+    "@strav/instant": {
+      "optional": true
+    },
     "@strav/mail": {
       "optional": true
     }

package/src/drivers/line/index.ts

@@ -0,0 +1,7 @@
+export type { LineChannelConfig } from './line_config.ts'
+export {
+  LineNotificationDriver,
+  type LineNotificationDriverOptions,
+  type LineNotificationMessage,
+} from './line_notification_driver.ts'
+export { LineNotificationProvider } from './line_notification_provider.ts'

package/src/drivers/line/line_config.ts

@@ -0,0 +1,30 @@
+/**
+ * Vendor-specific config shape for the LINE notification channel.
+ * Discriminator `driver: 'line'` selects this factory at
+ * `manager.use(...)` time.
+ *
+ * The LINE channel delegates to `@strav/instant`'s LINE driver under
+ * the hood — apps only configure which `config.instant.providers`
+ * entry to route through. Authentication / channel access tokens /
+ * webhook signature handling stay on `@strav/instant`.
+ */
+
+import type { ChannelConfig } from '../../notification_config.ts'
+
+export interface LineChannelConfig extends ChannelConfig {
+  driver: 'line'
+  /**
+   * Name of the `config.instant.providers` entry whose driver this
+   * channel should push through. Defaults to `'line'`. Apps running
+   * one LINE bot for support + another for marketing point each
+   * notification channel at the matching instance.
+   */
+  instantProvider?: string
+  /**
+   * Default display name shown when the hook returns a plain `string`.
+   * Apps almost never set this — LINE messages don't carry sender
+   * overrides the way Discord does — but it's surfaced to the hook in
+   * `defaults` so apps can branch on it.
+   */
+  sender?: string
+}

package/src/drivers/line/line_notification_driver.ts

@@ -0,0 +1,191 @@
+/**
+ * `LineNotificationDriver` — sends notifications via the LINE
+ * Messaging API by delegating to `@strav/instant`'s LINE driver.
+ *
+ * The notification system stays out of the LINE specifics — auth,
+ * webhook signature, Flex builder, rich menus all live in
+ * `@strav/instant/line`. This channel is the thin adapter from
+ * `BaseNotification` → `instant.use('line').push(...)` (single
+ * recipient) or `.multicast(...)` (≤500 recipients per LINE limit).
+ *
+ * Reads `notification.toLine(notifiable, defaults)` for the message.
+ * The hook can return:
+ *
+ *   - A `string` — shorthand for `{ text: <string> }` text-only push.
+ *   - An `OutgoingMessage` (from `@strav/instant`) — full envelope
+ *     with attachments / quick replies / Flex via `raw`.
+ *   - A `LineNotificationMessage` envelope with an optional `to`
+ *     override (single id or array — array triggers multicast).
+ *
+ * Recipient resolution order: hook `to` → `notifiable.lineUserIds`
+ * (multicast) → `notifiable.lineUserId` (single push). None resolved
+ * → `{ delivered: false }` with no error (same opt-out semantics as
+ * the mail / discord channels).
+ *
+ * Flex shortcut: pass a `flex` field on the envelope — the driver
+ * lifts it into `OutgoingMessage.raw` so apps don't have to know the
+ * `raw` plumbing. The Flex object itself comes from
+ * `@strav/instant/line`'s typed `flex.*` factories.
+ */
+
+import type { InstantManager } from '@strav/instant'
+import type { Notifiable } from '../../notifiable.ts'
+import type { BaseNotification } from '../../notification.ts'
+import type { NotificationDriver } from '../../notification_driver.ts'
+import { NotificationDeliveryError } from '../../notification_error.ts'
+import type { NotificationContext, NotificationDeliveryResult } from '../../types.ts'
+
+/** Shape returned by `notification.toLine(notifiable, defaults)`. */
+export interface LineNotificationMessage {
+  /** Plain-text body. */
+  text?: string
+  /** Native `@strav/instant` attachments (image / video / audio / location / sticker). */
+  attachments?: import('@strav/instant').Attachment[]
+  /** Native quick replies. */
+  quickReplies?: import('@strav/instant').QuickReply[]
+  /**
+   * Flex object — shortcut for `raw`. Build via `@strav/instant/line`'s
+   * `flex.bubble(...)` / `flex.carousel(...)` factories. The driver
+   * wraps it into a LINE Flex message envelope.
+   */
+  flex?: unknown
+  /**
+   * Override the recipient(s). A single string → push; an array of
+   * strings → multicast. When set, the driver ignores
+   * `notifiable.lineUserId(s)`.
+   */
+  to?: string | readonly string[]
+  /**
+   * Provider-native message object. When set, forwarded verbatim and
+   * supersedes the LCD fields above.
+   */
+  raw?: unknown
+}
+
+/** Hook surface — apps add `toLine(notifiable, defaults)` on their notification. */
+interface LineCapableNotification extends BaseNotification {
+  toLine?(
+    notifiable: Notifiable,
+    defaults: { sender?: string },
+  ):
+    | string
+    | LineNotificationMessage
+    | import('@strav/instant').OutgoingMessage
+    | Promise<string | LineNotificationMessage | import('@strav/instant').OutgoingMessage>
+}
+
+interface NotifiableWithLine extends Notifiable {
+  lineUserId?: string
+  lineUserIds?: readonly string[]
+}
+
+export interface LineNotificationDriverOptions {
+  name: string
+  manager: InstantManager
+  instantProvider?: string
+  sender?: string
+}
+
+export class LineNotificationDriver implements NotificationDriver {
+  readonly name: string
+  private readonly manager: InstantManager
+  private readonly instantProvider: string
+  private readonly sender: string | undefined
+
+  constructor(options: LineNotificationDriverOptions) {
+    this.name = options.name
+    this.manager = options.manager
+    this.instantProvider = options.instantProvider ?? 'line'
+    this.sender = options.sender
+  }
+
+  async send(
+    notifiable: Notifiable,
+    notification: BaseNotification,
+    context: NotificationContext,
+  ): Promise<NotificationDeliveryResult> {
+    const hook = (notification as LineCapableNotification).toLine
+    if (typeof hook !== 'function') {
+      return { channel: this.name, delivered: false }
+    }
+
+    const defaults = this.sender !== undefined ? { sender: this.sender } : {}
+    const raw = await hook.call(notification, notifiable, defaults)
+    const envelope = normaliseEnvelope(raw)
+
+    const to = resolveRecipients(envelope.to, notifiable)
+    if (to === null) {
+      return { channel: this.name, delivered: false }
+    }
+
+    const outgoing = toOutgoing(envelope)
+    const driver = this.manager.use(this.instantProvider)
+
+    try {
+      const result =
+        typeof to === 'string'
+          ? await driver.push!(to, outgoing)
+          : await driver.multicast!(to, outgoing)
+      return {
+        channel: this.name,
+        delivered: !!result.accepted,
+        ...(result.messageId ? { reference: result.messageId } : { reference: context.id }),
+      }
+    } catch (cause) {
+      throw new NotificationDeliveryError(
+        `LineNotificationDriver: delivery via instant provider "${this.instantProvider}" failed.`,
+        {
+          context: {
+            channel: this.name,
+            notifiableId: notifiable.id,
+            notification: notification.constructor.name,
+            instantProvider: this.instantProvider,
+            retryable: true,
+          },
+          cause,
+        },
+      )
+    }
+  }
+}
+
+function normaliseEnvelope(
+  raw: string | LineNotificationMessage | import('@strav/instant').OutgoingMessage,
+): LineNotificationMessage {
+  if (typeof raw === 'string') return { text: raw }
+  return raw as LineNotificationMessage
+}
+
+function resolveRecipients(
+  override: string | readonly string[] | undefined,
+  notifiable: Notifiable,
+): string | readonly string[] | null {
+  if (override !== undefined) {
+    if (Array.isArray(override)) return override.length > 0 ? override : null
+    return override || null
+  }
+  const n = notifiable as NotifiableWithLine
+  if (n.lineUserIds && n.lineUserIds.length > 0) return n.lineUserIds
+  if (n.lineUserId) return n.lineUserId
+  return null
+}
+
+function toOutgoing(
+  envelope: LineNotificationMessage,
+): import('@strav/instant').OutgoingMessage {
+  // Flex shortcut: lift the flex object into a LINE Flex message
+  // envelope on `raw`, where `@strav/instant/line`'s mapper forwards
+  // it verbatim to the wire.
+  if (envelope.flex !== undefined && envelope.raw === undefined) {
+    return {
+      ...(envelope.text !== undefined ? { text: envelope.text } : {}),
+      raw: [{ type: 'flex', altText: envelope.text ?? 'Notification', contents: envelope.flex }],
+    }
+  }
+  return {
+    ...(envelope.text !== undefined ? { text: envelope.text } : {}),
+    ...(envelope.attachments !== undefined ? { attachments: envelope.attachments } : {}),
+    ...(envelope.quickReplies !== undefined ? { quickReplies: envelope.quickReplies } : {}),
+    ...(envelope.raw !== undefined ? { raw: envelope.raw } : {}),
+  }
+}

package/src/drivers/line/line_notification_provider.ts

@@ -0,0 +1,32 @@
+/**
+ * ServiceProvider that registers the LINE channel factory on the
+ * `NotificationManager`. Apps include this in their provider list
+ * AFTER `NotificationProvider` AND `InstantProvider` — the factory
+ * resolves whenever `config.notification.channels.<name>.driver ===
+ * 'line'` and forwards through the matching `InstantManager` instance.
+ */
+
+import { InstantManager } from '@strav/instant'
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { NotificationManager } from '../../notification_manager.ts'
+import type { LineChannelConfig } from './line_config.ts'
+import { LineNotificationDriver } from './line_notification_driver.ts'
+
+export class LineNotificationProvider extends ServiceProvider {
+  override readonly name = 'notification.line'
+  override readonly dependencies = ['notification', 'instant']
+
+  override async boot(app: Application): Promise<void> {
+    const manager = app.resolve(NotificationManager)
+    const instant = app.resolve(InstantManager)
+    manager.extend('line', ({ instanceName, config }) => {
+      const cfg = config as LineChannelConfig
+      return new LineNotificationDriver({
+        name: instanceName,
+        manager: instant,
+        ...(cfg.instantProvider !== undefined ? { instantProvider: cfg.instantProvider } : {}),
+        ...(cfg.sender !== undefined ? { sender: cfg.sender } : {}),
+      })
+    })
+  }
+}