@stravigor/core 0.1.0

package/src/mail/types.ts

@@ -0,0 +1,80 @@
+/** Core message structure passed to transports. */
+export interface MailMessage {
+  from: string
+  to: string | string[]
+  cc?: string | string[]
+  bcc?: string | string[]
+  replyTo?: string
+  subject: string
+  html?: string
+  text?: string
+  attachments?: MailAttachment[]
+}
+
+export interface MailAttachment {
+  filename: string
+  content: Buffer | string
+  contentType?: string
+  /** For CID-referenced inline images. */
+  cid?: string
+}
+
+export interface MailResult {
+  messageId?: string
+  accepted?: string[]
+  rejected?: string[]
+}
+
+/**
+ * Pluggable transport backend.
+ * Implement this interface for custom mail providers.
+ */
+export interface MailTransport {
+  send(message: MailMessage): Promise<MailResult>
+}
+
+// -- Per-driver configs -------------------------------------------------------
+
+export interface SmtpConfig {
+  host: string
+  port: number
+  secure: boolean
+  auth?: {
+    user: string
+    pass: string
+  }
+}
+
+export interface ResendConfig {
+  apiKey: string
+  baseUrl?: string
+}
+
+export interface SendGridConfig {
+  apiKey: string
+  baseUrl?: string
+}
+
+export interface LogConfig {
+  /** Write to 'console' or a file path. */
+  output: 'console' | string
+}
+
+// -- Top-level mail config ----------------------------------------------------
+
+export interface MailConfig {
+  /** Default transport name: 'smtp' | 'resend' | 'sendgrid' | 'log' */
+  default: string
+  /** Default "from" address. */
+  from: string
+  /** Template prefix for ViewEngine (default: 'emails'). */
+  templatePrefix: string
+  /** Enable CSS inlining via juice (default: true). */
+  inlineCss: boolean
+  /** Enable Tailwind CSS compilation before inlining (default: false). */
+  tailwind: boolean
+  smtp: SmtpConfig
+  resend: ResendConfig
+  sendgrid: SendGridConfig
+  log: LogConfig
+}

package/src/notification/base_notification.ts

@@ -0,0 +1,67 @@
+import type {
+  Notifiable,
+  MailEnvelope,
+  DatabaseEnvelope,
+  WebhookEnvelope,
+  DiscordEnvelope,
+  NotificationPayload,
+} from './types.ts'
+
+/**
+ * Base class for all notifications.
+ *
+ * Extend this class and implement `via()` plus at least one `toXxx()` method
+ * to define how the notification should be delivered on each channel.
+ *
+ * @example
+ * class TaskAssignedNotification extends BaseNotification {
+ *   constructor(private task: Task, private assigner: User) { super() }
+ *
+ *   via() { return ['email', 'database'] }
+ *
+ *   toEmail(notifiable: Notifiable): MailEnvelope {
+ *     return { subject: `Assigned: ${this.task.title}`, template: 'task-assigned', templateData: { ... } }
+ *   }
+ *
+ *   toDatabase(): DatabaseEnvelope {
+ *     return { type: 'task.assigned', data: { taskId: this.task.id } }
+ *   }
+ *
+ *   shouldQueue() { return true }
+ * }
+ */
+export abstract class BaseNotification {
+  /** Which channels this notification should be sent on. */
+  abstract via(notifiable: Notifiable): string[]
+
+  /** Build the email envelope. */
+  toEmail?(notifiable: Notifiable): MailEnvelope
+  /** Build the database (in-app) envelope. */
+  toDatabase?(notifiable: Notifiable): DatabaseEnvelope
+  /** Build the webhook envelope. */
+  toWebhook?(notifiable: Notifiable): WebhookEnvelope
+  /** Build the Discord envelope. */
+  toDiscord?(notifiable: Notifiable): DiscordEnvelope
+
+  /** Whether this notification should be queued for async delivery. */
+  shouldQueue(): boolean {
+    return false
+  }
+
+  /** Queue options (queue name, delay in ms, max attempts). */
+  queueOptions(): { queue?: string; delay?: number; attempts?: number } {
+    return {}
+  }
+
+  /** Build a serializable payload containing all channel envelopes. */
+  buildPayload(notifiable: Notifiable): NotificationPayload {
+    return {
+      notificationClass: this.constructor.name,
+      channels: this.via(notifiable),
+      mail: this.toEmail?.(notifiable),
+      database: this.toDatabase?.(notifiable),
+      webhook: this.toWebhook?.(notifiable),
+      discord: this.toDiscord?.(notifiable),
+    }
+  }
+}

package/src/notification/channels/database_channel.ts

@@ -0,0 +1,30 @@
+import type { NotificationChannel, Notifiable, NotificationPayload } from '../types.ts'
+import Database from '../../database/database.ts'
+
+/**
+ * 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,43 @@
+import { ExternalServiceError } from '../../exceptions/errors.ts'
+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,45 @@
+import { ExternalServiceError } from '../../exceptions/errors.ts'
+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 '../queue/queue.ts'
+import Emitter from '../events/emitter.ts'
+import Database from '../database/database.ts'
+
+/**
+ * Send a notification to one or more recipients.
+ *
+ * @example
+ * import { notify } from '@stravigor/core/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/core/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(
+            Array.isArray(recipients) ? recipients : [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,126 @@
+import { inject } from '../core/inject.ts'
+import Configuration from '../config/configuration.ts'
+import Database from '../database/database.ts'
+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 '../exceptions/errors.ts'
+
+/**
+ * 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()
+  }
+}