@strav/signal 0.1.0

package/src/notification/channels/database_channel.ts

@@ -0,0 +1,30 @@
+import type { NotificationChannel, Notifiable, NotificationPayload } from '../types.ts'
+import Database from '@stravigor/database/database/database'
+
+/**
+ * Stores notifications in the `_strav_notifications` table.
+ *
+ * The database channel enables in-app notification features
+ * (unread badges, notification feeds, etc.).
+ */
+export class DatabaseChannel implements NotificationChannel {
+  readonly name = 'database'
+
+  async send(notifiable: Notifiable, payload: NotificationPayload): Promise<void> {
+    const envelope = payload.database
+    if (!envelope) return
+
+    const sql = Database.raw
+
+    await sql`
+      INSERT INTO "_strav_notifications"
+        ("notifiable_type", "notifiable_id", "type", "data")
+      VALUES (
+        ${notifiable.notifiableType()},
+        ${String(notifiable.notifiableId())},
+        ${envelope.type},
+        ${JSON.stringify(envelope.data)}
+      )
+    `
+  }
+}

package/src/notification/channels/discord_channel.ts

@@ -0,0 +1,48 @@
+import { ExternalServiceError } from '@stravigor/kernel/exceptions/errors'
+import type {
+  NotificationChannel,
+  Notifiable,
+  NotificationPayload,
+  NotificationConfig,
+} from '../types.ts'
+
+/**
+ * Delivers notifications via Discord webhook.
+ *
+ * URL resolution order:
+ * 1. `DiscordEnvelope.url` (per-notification override)
+ * 2. `notifiable.routeNotificationForDiscord()` (per-recipient)
+ * 3. Config discord `default` entry
+ */
+export class DiscordChannel implements NotificationChannel {
+  readonly name = 'discord'
+
+  constructor(private config: NotificationConfig) {}
+
+  async send(notifiable: Notifiable, payload: NotificationPayload): Promise<void> {
+    const envelope = payload.discord
+    if (!envelope) return
+
+    const url =
+      envelope.url ??
+      notifiable.routeNotificationForDiscord?.() ??
+      this.config.discord?.default ??
+      null
+
+    if (!url) return
+
+    const body: Record<string, unknown> = {}
+    if (envelope.content) body.content = envelope.content
+    if (envelope.embeds?.length) body.embeds = envelope.embeds
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      throw new ExternalServiceError('Discord', response.status, await response.text())
+    }
+  }
+}

package/src/notification/channels/email_channel.ts

@@ -0,0 +1,37 @@
+import type { NotificationChannel, Notifiable, NotificationPayload } from '../types.ts'
+import { PendingMail } from '../../mail/helpers.ts'
+
+/**
+ * Delivers notifications via the existing Mail module.
+ *
+ * Reads the email address from `notifiable.routeNotificationForEmail()`
+ * and builds a {@link PendingMail} from the {@link MailEnvelope}.
+ */
+export class EmailChannel implements NotificationChannel {
+  readonly name = 'email'
+
+  async send(notifiable: Notifiable, payload: NotificationPayload): Promise<void> {
+    const envelope = payload.mail
+    if (!envelope) return
+
+    const address = notifiable.routeNotificationForEmail?.()
+    if (!address) return
+
+    const pending = new PendingMail(address).subject(envelope.subject)
+
+    if (envelope.from) pending.from(envelope.from)
+    if (envelope.cc) pending.cc(envelope.cc)
+    if (envelope.bcc) pending.bcc(envelope.bcc)
+    if (envelope.replyTo) pending.replyTo(envelope.replyTo)
+
+    if (envelope.template) {
+      pending.template(envelope.template, envelope.templateData ?? {})
+    } else if (envelope.html) {
+      pending.html(envelope.html)
+    }
+
+    if (envelope.text) pending.text(envelope.text)
+
+    await pending.send()
+  }
+}

package/src/notification/channels/webhook_channel.ts

@@ -0,0 +1,50 @@
+import { ExternalServiceError } from '@stravigor/kernel/exceptions/errors'
+import type {
+  NotificationChannel,
+  Notifiable,
+  NotificationPayload,
+  NotificationConfig,
+} from '../types.ts'
+
+/**
+ * Delivers notifications via HTTP POST to a webhook URL.
+ *
+ * URL resolution order:
+ * 1. `WebhookEnvelope.url` (per-notification override)
+ * 2. `notifiable.routeNotificationForWebhook()` (per-recipient)
+ * 3. Config webhooks `default` entry
+ */
+export class WebhookChannel implements NotificationChannel {
+  readonly name = 'webhook'
+
+  constructor(private config: NotificationConfig) {}
+
+  async send(notifiable: Notifiable, payload: NotificationPayload): Promise<void> {
+    const envelope = payload.webhook
+    if (!envelope) return
+
+    const url =
+      envelope.url ??
+      notifiable.routeNotificationForWebhook?.() ??
+      this.config.webhooks?.default?.url ??
+      null
+
+    if (!url) return
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...this.config.webhooks?.default?.headers,
+      ...envelope.headers,
+    }
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(envelope.payload),
+    })
+
+    if (!response.ok) {
+      throw new ExternalServiceError('Webhook', response.status, await response.text())
+    }
+  }
+}

package/src/notification/helpers.ts

@@ -0,0 +1,214 @@
+import NotificationManager from './notification_manager.ts'
+import type { BaseNotification } from './base_notification.ts'
+import type { Notifiable, NotificationRecord } from './types.ts'
+import Queue from '@stravigor/queue/queue/queue'
+import Emitter from '@stravigor/kernel/events/emitter'
+import Database from '@stravigor/database/database/database'
+
+/**
+ * Send a notification to one or more recipients.
+ *
+ * @example
+ * import { notify } from '@stravigor/signal/notification'
+ *
+ * await notify(user, new TaskAssignedNotification(task, assigner))
+ * await notify([user1, user2], new InvoicePaidNotification(invoice))
+ */
+export async function notify(
+  notifiable: Notifiable | Notifiable[],
+  notification: BaseNotification
+): Promise<void> {
+  const recipients = Array.isArray(notifiable) ? notifiable : [notifiable]
+
+  for (const recipient of recipients) {
+    if (notification.shouldQueue()) {
+      const payload = notification.buildPayload(recipient)
+
+      // Pre-resolve routing info so channels can deliver from the queue worker
+      const routing: Record<string, string> = {}
+      const email = recipient.routeNotificationForEmail?.()
+      if (email) routing.email = email
+      const webhook = recipient.routeNotificationForWebhook?.()
+      if (webhook) routing.webhook = webhook
+      const discord = recipient.routeNotificationForDiscord?.()
+      if (discord) routing.discord = discord
+
+      await Queue.push(
+        'strav:send-notification',
+        {
+          notifiable: { id: recipient.notifiableId(), type: recipient.notifiableType() },
+          routing,
+          payload,
+        },
+        {
+          queue: notification.queueOptions().queue ?? NotificationManager.config.queue,
+          delay: notification.queueOptions().delay,
+          attempts: notification.queueOptions().attempts,
+        }
+      )
+    } else {
+      await sendNow(recipient, notification)
+    }
+  }
+}
+
+/** Send a notification immediately (bypasses queue). */
+async function sendNow(notifiable: Notifiable, notification: BaseNotification): Promise<void> {
+  const payload = notification.buildPayload(notifiable)
+
+  for (const channelName of payload.channels) {
+    const channel = NotificationManager.channel(channelName)
+    await channel.send(notifiable, payload)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// In-app notification query helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Notification query helper — convenience API for in-app notification reads.
+ *
+ * @example
+ * import { notifications } from '@stravigor/signal/notification'
+ *
+ * const unread = await notifications.unread('user', userId)
+ * await notifications.markAsRead(notificationId)
+ * await notifications.markAllAsRead('user', userId)
+ */
+export const notifications = {
+  /** Get all notifications for a notifiable, newest first. */
+  async all(type: string, id: string | number, limit = 50): Promise<NotificationRecord[]> {
+    const sql = Database.raw
+    const rows = await sql`
+      SELECT * FROM "_strav_notifications"
+      WHERE "notifiable_type" = ${type} AND "notifiable_id" = ${String(id)}
+      ORDER BY "created_at" DESC
+      LIMIT ${limit}
+    `
+    return rows.map(hydrateNotification)
+  },
+
+  /** Get unread notifications for a notifiable. */
+  async unread(type: string, id: string | number, limit = 50): Promise<NotificationRecord[]> {
+    const sql = Database.raw
+    const rows = await sql`
+      SELECT * FROM "_strav_notifications"
+      WHERE "notifiable_type" = ${type}
+        AND "notifiable_id" = ${String(id)}
+        AND "read_at" IS NULL
+      ORDER BY "created_at" DESC
+      LIMIT ${limit}
+    `
+    return rows.map(hydrateNotification)
+  },
+
+  /** Count unread notifications. */
+  async unreadCount(type: string, id: string | number): Promise<number> {
+    const sql = Database.raw
+    const rows = await sql`
+      SELECT COUNT(*)::int AS count FROM "_strav_notifications"
+      WHERE "notifiable_type" = ${type}
+        AND "notifiable_id" = ${String(id)}
+        AND "read_at" IS NULL
+    `
+    return (rows[0] as Record<string, unknown>).count as number
+  },
+
+  /** Mark a single notification as read. */
+  async markAsRead(id: string): Promise<void> {
+    const sql = Database.raw
+    await sql`
+      UPDATE "_strav_notifications"
+      SET "read_at" = NOW()
+      WHERE "id" = ${id} AND "read_at" IS NULL
+    `
+  },
+
+  /** Mark all notifications as read for a notifiable. */
+  async markAllAsRead(type: string, id: string | number): Promise<void> {
+    const sql = Database.raw
+    await sql`
+      UPDATE "_strav_notifications"
+      SET "read_at" = NOW()
+      WHERE "notifiable_type" = ${type}
+        AND "notifiable_id" = ${String(id)}
+        AND "read_at" IS NULL
+    `
+  },
+
+  /** Delete a single notification. */
+  async delete(id: string): Promise<void> {
+    const sql = Database.raw
+    await sql`DELETE FROM "_strav_notifications" WHERE "id" = ${id}`
+  },
+
+  /** Delete all notifications for a notifiable. */
+  async deleteAll(type: string, id: string | number): Promise<void> {
+    const sql = Database.raw
+    await sql`
+      DELETE FROM "_strav_notifications"
+      WHERE "notifiable_type" = ${type} AND "notifiable_id" = ${String(id)}
+    `
+  },
+
+  /**
+   * Register the built-in queue handler for async notification delivery.
+   * Call this in your app bootstrap after Queue and NotificationManager are configured.
+   */
+  registerQueueHandler(): void {
+    Queue.handle('strav:send-notification', async (job: any) => {
+      const { notifiable: ref, routing, payload } = job
+
+      // Reconstruct a minimal Notifiable proxy with pre-resolved routing
+      const notifiable: Notifiable = {
+        notifiableId: () => ref.id,
+        notifiableType: () => ref.type,
+        routeNotificationForEmail: () => routing?.email ?? null,
+        routeNotificationForWebhook: () => routing?.webhook ?? null,
+        routeNotificationForDiscord: () => routing?.discord ?? null,
+      }
+
+      for (const channelName of payload.channels) {
+        const channel = NotificationManager.channel(channelName)
+        await channel.send(notifiable, payload)
+      }
+    })
+  },
+
+  /**
+   * Wire event-to-notification mappings to the Emitter.
+   * Call this once during bootstrap after registering all bindings via
+   * {@link NotificationManager.on}.
+   */
+  wireEvents(): void {
+    for (const [event, bindings] of NotificationManager.eventBindings()) {
+      Emitter.on(event, async (eventPayload: any) => {
+        for (const binding of bindings) {
+          const notification = binding.create(eventPayload)
+          const recipients = await binding.recipients(eventPayload)
+          await notify(recipients, notification)
+        }
+      })
+    }
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Hydration
+// ---------------------------------------------------------------------------
+
+function hydrateNotification(row: Record<string, unknown>): NotificationRecord {
+  return {
+    id: row.id as string,
+    notifiableType: row.notifiable_type as string,
+    notifiableId: row.notifiable_id as string,
+    type: row.type as string,
+    data: (typeof row.data === 'string' ? JSON.parse(row.data) : row.data) as Record<
+      string,
+      unknown
+    >,
+    readAt: (row.read_at as Date) ?? null,
+    createdAt: row.created_at as Date,
+  }
+}

package/src/notification/index.ts

@@ -0,0 +1,20 @@
+export { default, default as NotificationManager } from './notification_manager.ts'
+export { BaseNotification } from './base_notification.ts'
+export { notify, notifications } from './helpers.ts'
+export { EmailChannel } from './channels/email_channel.ts'
+export { DatabaseChannel } from './channels/database_channel.ts'
+export { WebhookChannel } from './channels/webhook_channel.ts'
+export { DiscordChannel } from './channels/discord_channel.ts'
+export type {
+  NotificationChannel,
+  Notifiable,
+  NotificationPayload,
+  NotificationRecord,
+  NotificationConfig,
+  MailEnvelope,
+  DatabaseEnvelope,
+  WebhookEnvelope,
+  DiscordEnvelope,
+  DiscordEmbed,
+  EventNotificationBinding,
+} from './types.ts'

package/src/notification/notification_manager.ts

@@ -0,0 +1,127 @@
+import { inject } from '@stravigor/kernel/core/inject'
+import Configuration from '@stravigor/kernel/config/configuration'
+import Database from '@stravigor/database/database/database'
+import type { NotificationChannel, NotificationConfig, EventNotificationBinding } from './types.ts'
+import { EmailChannel } from './channels/email_channel.ts'
+import { DatabaseChannel } from './channels/database_channel.ts'
+import { WebhookChannel } from './channels/webhook_channel.ts'
+import { DiscordChannel } from './channels/discord_channel.ts'
+import { ConfigurationError } from '@stravigor/kernel/exceptions/errors'
+
+/**
+ * Central notification configuration hub.
+ *
+ * Resolved once via the DI container — reads the notification config,
+ * registers built-in channels, and provides an event-to-notification registry.
+ *
+ * @example
+ * app.singleton(NotificationManager)
+ * app.resolve(NotificationManager)
+ * await NotificationManager.ensureTable()
+ *
+ * // Register a custom channel
+ * NotificationManager.useChannel(new SlackChannel())
+ */
+@inject
+export default class NotificationManager {
+  private static _db: Database
+  private static _config: NotificationConfig
+  private static _channels = new Map<string, NotificationChannel>()
+  private static _eventMap = new Map<string, EventNotificationBinding[]>()
+
+  constructor(db: Database, config: Configuration) {
+    NotificationManager._db = db
+    NotificationManager._config = {
+      channels: config.get('notification.channels', ['database']) as string[],
+      queue: config.get('notification.queue', 'default') as string,
+      webhooks: config.get('notification.webhooks', {}) as Record<
+        string,
+        { url: string; headers?: Record<string, string> }
+      >,
+      discord: config.get('notification.discord', {}) as Record<string, string>,
+    }
+
+    // Register built-in channels
+    NotificationManager._channels.set('email', new EmailChannel())
+    NotificationManager._channels.set('database', new DatabaseChannel())
+    NotificationManager._channels.set('webhook', new WebhookChannel(NotificationManager._config))
+    NotificationManager._channels.set('discord', new DiscordChannel(NotificationManager._config))
+  }
+
+  static get db(): Database {
+    if (!NotificationManager._db) {
+      throw new Error('NotificationManager not configured. Resolve it through the container first.')
+    }
+    return NotificationManager._db
+  }
+
+  static get config(): NotificationConfig {
+    return NotificationManager._config
+  }
+
+  /** Get a registered channel by name. */
+  static channel(name: string): NotificationChannel {
+    const ch = NotificationManager._channels.get(name)
+    if (!ch) throw new ConfigurationError(`Unknown notification channel: ${name}`)
+    return ch
+  }
+
+  /** Register a custom notification channel (or replace a built-in one). */
+  static useChannel(channel: NotificationChannel): void {
+    NotificationManager._channels.set(channel.name, channel)
+  }
+
+  /** Create the _strav_notifications table if it doesn't exist. */
+  static async ensureTable(): Promise<void> {
+    const sql = NotificationManager.db.sql
+
+    await sql`
+      CREATE TABLE IF NOT EXISTS "_strav_notifications" (
+        "id" UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        "notifiable_type" VARCHAR(255) NOT NULL,
+        "notifiable_id" VARCHAR(255) NOT NULL,
+        "type" VARCHAR(255) NOT NULL,
+        "data" JSONB NOT NULL DEFAULT '{}',
+        "read_at" TIMESTAMPTZ,
+        "created_at" TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      )
+    `
+
+    await sql`
+      CREATE INDEX IF NOT EXISTS "idx_strav_notifications_notifiable"
+        ON "_strav_notifications" ("notifiable_type", "notifiable_id", "created_at" DESC)
+    `
+
+    await sql`
+      CREATE INDEX IF NOT EXISTS "idx_strav_notifications_unread"
+        ON "_strav_notifications" ("notifiable_type", "notifiable_id")
+        WHERE "read_at" IS NULL
+    `
+  }
+
+  /**
+   * Register an event-to-notification mapping.
+   *
+   * @example
+   * NotificationManager.on('task.assigned', {
+   *   create: (payload) => new TaskAssignedNotification(payload.task, payload.assigner),
+   *   recipients: (payload) => payload.assignee,
+   * })
+   */
+  static on(event: string, binding: EventNotificationBinding): void {
+    const existing = NotificationManager._eventMap.get(event) ?? []
+    existing.push(binding)
+    NotificationManager._eventMap.set(event, existing)
+  }
+
+  /** Expose the event map (used by wireEvents). */
+  static eventBindings(): Map<string, EventNotificationBinding[]> {
+    return NotificationManager._eventMap
+  }
+
+  /** Clear all state. For testing only. */
+  static reset(): void {
+    NotificationManager._channels.clear()
+    NotificationManager._eventMap.clear()
+  }
+}

package/src/notification/types.ts

@@ -0,0 +1,122 @@
+/** A recipient that can receive notifications. */
+export interface Notifiable {
+  /** Unique identifier for the notifiable entity. */
+  notifiableId(): string | number
+  /** Type discriminator (e.g., 'user', 'organization'). */
+  notifiableType(): string
+  /** Email address for the email channel. Returns null to skip email. */
+  routeNotificationForEmail?(): string | null
+  /** Webhook URL for the webhook channel. Returns null to skip. */
+  routeNotificationForWebhook?(): string | null
+  /** Discord webhook URL. Returns null to skip. */
+  routeNotificationForDiscord?(): string | null
+}
+
+// -- Channel envelopes --------------------------------------------------------
+
+/** Envelope produced by a notification for the email channel. */
+export interface MailEnvelope {
+  subject: string
+  template?: string
+  templateData?: Record<string, unknown>
+  html?: string
+  text?: string
+  from?: string
+  cc?: string | string[]
+  bcc?: string | string[]
+  replyTo?: string
+}
+
+/** Envelope produced by a notification for the database (in-app) channel. */
+export interface DatabaseEnvelope {
+  /** Notification type / category (e.g., 'task.assigned', 'invoice.paid'). */
+  type: string
+  /** Structured data stored as JSONB. */
+  data: Record<string, unknown>
+}
+
+/** Envelope produced by a notification for the webhook channel. */
+export interface WebhookEnvelope {
+  /** JSON payload to POST. */
+  payload: Record<string, unknown>
+  /** Optional custom headers. */
+  headers?: Record<string, string>
+  /** Override the webhook URL from notifiable routing. */
+  url?: string
+}
+
+/** Envelope produced by a notification for the Discord channel. */
+export interface DiscordEnvelope {
+  /** Plain text content. */
+  content?: string
+  /** Discord embed objects. */
+  embeds?: DiscordEmbed[]
+  /** Override the webhook URL from notifiable routing. */
+  url?: string
+}
+
+export interface DiscordEmbed {
+  title?: string
+  description?: string
+  url?: string
+  color?: number
+  fields?: { name: string; value: string; inline?: boolean }[]
+  footer?: { text: string }
+  timestamp?: string
+}
+
+// -- Channel interface --------------------------------------------------------
+
+/** Serializable envelope bundle built by BaseNotification. */
+export interface NotificationPayload {
+  notificationClass: string
+  channels: string[]
+  mail?: MailEnvelope
+  database?: DatabaseEnvelope
+  webhook?: WebhookEnvelope
+  discord?: DiscordEnvelope
+}
+
+/**
+ * Pluggable notification channel backend.
+ * Implement this interface for custom channels.
+ */
+export interface NotificationChannel {
+  readonly name: string
+  send(notifiable: Notifiable, payload: NotificationPayload): Promise<void>
+}
+
+// -- Database records ---------------------------------------------------------
+
+/** A stored in-app notification row. */
+export interface NotificationRecord {
+  id: string
+  notifiableType: string
+  notifiableId: string
+  type: string
+  data: Record<string, unknown>
+  readAt: Date | null
+  createdAt: Date
+}
+
+// -- Configuration ------------------------------------------------------------
+
+export interface NotificationConfig {
+  /** Default channels when a notification does not specify via(). */
+  channels: string[]
+  /** Queue name for async notifications. */
+  queue: string
+  /** Named webhook endpoints. */
+  webhooks: Record<string, { url: string; headers?: Record<string, string> }>
+  /** Named Discord webhook URLs. */
+  discord: Record<string, string>
+}
+
+// -- Event binding ------------------------------------------------------------
+
+export interface EventNotificationBinding {
+  /** Factory that creates the notification from the event payload. */
+  create: (payload: any) => import('./base_notification.ts').BaseNotification
+  /** Resolves which notifiable(s) should receive this notification. */
+  recipients: (payload: any) => Notifiable | Notifiable[] | Promise<Notifiable | Notifiable[]>
+}

package/src/providers/broadcast_provider.ts

@@ -0,0 +1,22 @@
+import ServiceProvider from '@stravigor/kernel/core/service_provider'
+import type Application from '@stravigor/kernel/core/application'
+import BroadcastManager from '../broadcast/broadcast_manager.ts'
+import type { BootOptions } from '../broadcast/broadcast_manager.ts'
+import Router from '@stravigor/http/http/router'
+
+export default class BroadcastProvider extends ServiceProvider {
+  readonly name = 'broadcast'
+
+  constructor(private options?: BootOptions) {
+    super()
+  }
+
+  override boot(app: Application): void {
+    const router = app.resolve(Router)
+    BroadcastManager.boot(router, this.options)
+  }
+
+  override shutdown(): void {
+    BroadcastManager.reset()
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,5 @@
+export { default as MailProvider } from './mail_provider.ts'
+export { default as NotificationProvider } from './notification_provider.ts'
+export { default as BroadcastProvider } from './broadcast_provider.ts'
+
+export type { NotificationProviderOptions } from './notification_provider.ts'