@mantiq/notify 0.1.0

package/README.md

@@ -0,0 +1,9 @@
+# @mantiq/notify
+
+Multi-channel notifications for [MantiqJS](https://github.com/mantiqjs/mantiq).
+
+Built-in channels: mail, database, broadcast, SMS, Slack, webhook. Extensible — any package can register custom channels.
+
+```bash
+bun add @mantiq/notify
+```

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@mantiq/notify",
+  "version": "0.1.0",
+  "description": "Multi-channel notifications — mail, database, broadcast, SMS, Slack, webhook",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/mantiqjs/mantiq/tree/main/packages/notify",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mantiqjs/mantiq.git",
+    "directory": "packages/notify"
+  },
+  "bugs": {
+    "url": "https://github.com/mantiqjs/mantiq/issues"
+  },
+  "keywords": [
+    "mantiq",
+    "mantiqjs",
+    "bun",
+    "typescript",
+    "framework",
+    "notifications",
+    "mail",
+    "sms",
+    "slack"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "@mantiq/core": "^0.1.0",
+    "@mantiq/database": "^0.1.0",
+    "@mantiq/mail": "^0.2.0",
+    "@mantiq/events": "^0.1.0",
+    "@mantiq/realtime": "^0.1.0",
+    "@mantiq/queue": "^0.1.0",
+    "@mantiq/cli": "^0.1.0"
+  }
+}

package/src/Notification.ts

@@ -0,0 +1,102 @@
+import type { Notifiable } from './contracts/Notifiable.ts'
+import type { Mailable } from '@mantiq/mail'
+
+export interface SlackMessage {
+  text?: string
+  blocks?: any[]
+  channel?: string
+  username?: string
+  iconEmoji?: string
+  iconUrl?: string
+}
+
+export interface BroadcastPayload {
+  event: string
+  data: any
+  channel?: string
+}
+
+export interface SmsPayload {
+  to?: string
+  body: string
+}
+
+export interface WebhookPayload {
+  url: string
+  body: any
+  method?: 'POST' | 'PUT' | 'PATCH'
+  headers?: Record<string, string>
+}
+
+/**
+ * Base notification class. Users extend this and implement via() + to{Channel}() methods.
+ *
+ * @example
+ *   class OrderShipped extends Notification {
+ *     constructor(private order: Order) { super() }
+ *
+ *     via(notifiable: Notifiable) { return ['mail', 'database'] }
+ *
+ *     toMail(notifiable: Notifiable) {
+ *       return new OrderShippedEmail(this.order)
+ *     }
+ *
+ *     toDatabase(notifiable: Notifiable) {
+ *       return { order_id: this.order.id, message: 'Your order shipped' }
+ *     }
+ *   }
+ *
+ * Convention: channel "foo" calls this.toFoo(notifiable).
+ * Any method matching to{ChannelName} will be called by that channel.
+ * This makes the system infinitely extensible — no core changes needed.
+ */
+export abstract class Notification {
+  /** Unique ID for this notification instance */
+  id: string = crypto.randomUUID()
+
+  /** Which channels to deliver through */
+  abstract via(notifiable: Notifiable): string[]
+
+  // ── Built-in channel methods (optional) ─────────────────────────────────
+
+  toMail?(notifiable: Notifiable): Mailable
+  toDatabase?(notifiable: Notifiable): Record<string, any>
+  toBroadcast?(notifiable: Notifiable): BroadcastPayload
+  toSms?(notifiable: Notifiable): SmsPayload
+  toSlack?(notifiable: Notifiable): SlackMessage
+  toWebhook?(notifiable: Notifiable): WebhookPayload
+
+  // ── Queueing ──────────────────────────────────────────────────────────────
+
+  /** Override to true to queue this notification instead of sending immediately */
+  shouldQueue = false
+
+  /** Queue name override */
+  queue?: string
+
+  /** Queue connection override */
+  connection?: string
+
+  /** Max retry attempts */
+  tries = 3
+
+  // ── Internal helpers ──────────────────────────────────────────────────────
+
+  /** Get the notification type name (used in database channel) */
+  get type(): string {
+    return this.constructor.name
+  }
+
+  /**
+   * Get the channel-specific payload via convention.
+   * Channel "foo" → calls this.toFoo(notifiable).
+   */
+  getPayloadFor(channel: string, notifiable: Notifiable): any {
+    const methodName = `to${channel.charAt(0).toUpperCase()}${channel.slice(1)}`
+    const method = (this as any)[methodName]
+    if (typeof method === 'function') {
+      return method.call(this, notifiable)
+    }
+    return undefined
+  }
+}

package/src/NotificationManager.ts

@@ -0,0 +1,128 @@
+import type { NotificationChannel } from './contracts/Channel.ts'
+import type { Notifiable } from './contracts/Notifiable.ts'
+import type { NotifyConfig } from './contracts/NotifyConfig.ts'
+import { DEFAULT_CONFIG } from './contracts/NotifyConfig.ts'
+import { Notification } from './Notification.ts'
+import { NotifyError } from './errors/NotifyError.ts'
+import { MailChannel } from './channels/MailChannel.ts'
+import { DatabaseChannel } from './channels/DatabaseChannel.ts'
+import { BroadcastChannel } from './channels/BroadcastChannel.ts'
+import { SmsChannel } from './channels/SmsChannel.ts'
+import { SlackChannel } from './channels/SlackChannel.ts'
+import { WebhookChannel } from './channels/WebhookChannel.ts'
+
+/**
+ * NotificationManager — routes notifications through channels.
+ *
+ * Built-in channels: mail, database, broadcast, sms, slack, webhook.
+ * Extensible via extend() — any package can register custom channels.
+ *
+ * @example
+ *   await notify().send(user, new OrderShipped(order))
+ *   await notify().send([user1, user2], new OrderShipped(order))
+ */
+export class NotificationManager {
+  private _channels = new Map<string, NotificationChannel>()
+  private _factories = new Map<string, () => NotificationChannel>()
+  private config: NotifyConfig
+
+  constructor(config?: Partial<NotifyConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+    this.registerBuiltInChannels()
+  }
+
+  /** Send a notification to one or many notifiables */
+  async send(notifiable: Notifiable | Notifiable[], notification: Notification): Promise<void> {
+    const notifiables = Array.isArray(notifiable) ? notifiable : [notifiable]
+
+    if (notification.shouldQueue) {
+      for (const n of notifiables) {
+        await this.queueNotification(n, notification)
+      }
+      return
+    }
+
+    for (const n of notifiables) {
+      await this.sendNow(n, notification)
+    }
+  }
+
+  /** Send immediately, bypassing queue */
+  async sendNow(notifiable: Notifiable, notification: Notification, channelNames?: string[]): Promise<void> {
+    const channels = channelNames ?? notification.via(notifiable)
+
+    for (const channelName of channels) {
+      try {
+        const channel = this.channel(channelName)
+        await channel.send(notifiable, notification)
+      } catch (err) {
+        // Log but don't fail other channels
+        console.error(`[Mantiq] Notification channel "${channelName}" failed:`, (err as Error).message)
+      }
+    }
+  }
+
+  /** Get a channel by name */
+  channel(name: string): NotificationChannel {
+    if (this._channels.has(name)) return this._channels.get(name)!
+
+    const factory = this._factories.get(name)
+    if (factory) {
+      const channel = factory()
+      this._channels.set(name, channel)
+      return channel
+    }
+
+    throw new NotifyError(`Notification channel "${name}" is not registered.`, {
+      available: this.channelNames(),
+    })
+  }
+
+  /** Register a custom channel — this is the extension point */
+  extend(name: string, channel: NotificationChannel | (() => NotificationChannel)): void {
+    if (typeof channel === 'function') {
+      this._factories.set(name, channel)
+      this._channels.delete(name) // clear cache
+    } else {
+      this._channels.set(name, channel)
+    }
+  }
+
+  /** Check if a channel is registered */
+  hasChannel(name: string): boolean {
+    return this._channels.has(name) || this._factories.has(name)
+  }
+
+  /** List all registered channel names */
+  channelNames(): string[] {
+    return [...new Set([...this._channels.keys(), ...this._factories.keys()])]
+  }
+
+  // ── Private ───────────────────────────────────────────────────────────────
+
+  private registerBuiltInChannels(): void {
+    this._channels.set('mail', new MailChannel())
+    this._channels.set('database', new DatabaseChannel())
+    this._channels.set('broadcast', new BroadcastChannel())
+    this._channels.set('webhook', new WebhookChannel())
+
+    // Lazy-load SMS and Slack (need config)
+    if (this.config.channels?.sms) {
+      this._factories.set('sms', () => new SmsChannel(this.config.channels!.sms!))
+    }
+    if (this.config.channels?.slack) {
+      this._factories.set('slack', () => new SlackChannel(this.config.channels!.slack!))
+    }
+  }
+
+  private async queueNotification(notifiable: Notifiable, notification: Notification): Promise<void> {
+    try {
+      const { dispatch } = await import('@mantiq/queue')
+      const { SendNotificationJob } = await import('./jobs/SendNotificationJob.ts')
+      await dispatch(new SendNotificationJob(notifiable, notification))
+    } catch {
+      // Queue not available — send synchronously
+      await this.sendNow(notifiable, notification)
+    }
+  }
+}

package/src/NotificationServiceProvider.ts

@@ -0,0 +1,14 @@
+import { ServiceProvider, ConfigRepository } from '@mantiq/core'
+import { NotificationManager } from './NotificationManager.ts'
+import { NOTIFY_MANAGER } from './helpers/notify.ts'
+import type { NotifyConfig } from './contracts/NotifyConfig.ts'
+import { DEFAULT_CONFIG } from './contracts/NotifyConfig.ts'
+
+export class NotificationServiceProvider extends ServiceProvider {
+  override register(): void {
+    const config = this.app.make(ConfigRepository).get<NotifyConfig>('notify', DEFAULT_CONFIG)
+
+    this.app.singleton(NotificationManager, () => new NotificationManager(config))
+    this.app.alias(NotificationManager, NOTIFY_MANAGER)
+  }
+}

package/src/channels/BroadcastChannel.ts

@@ -0,0 +1,51 @@
+import type { NotificationChannel } from '../contracts/Channel.ts'
+import type { Notifiable } from '../contracts/Notifiable.ts'
+import type { Notification } from '../Notification.ts'
+import { NotifyError } from '../errors/NotifyError.ts'
+
+/**
+ * Broadcasts notifications via server-sent events using @mantiq/realtime.
+ *
+ * The notification's `toBroadcast(notifiable)` method should return a
+ * `BroadcastPayload` with `{ event, data, channel? }`.
+ *
+ * If no channel is specified, defaults to `App.User.{notifiable.getKey()}`.
+ * If @mantiq/realtime is not installed, the channel skips silently.
+ */
+export class BroadcastChannel implements NotificationChannel {
+  readonly name = 'broadcast'
+
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    const payload = notification.getPayloadFor('broadcast', notifiable)
+    if (!payload) return
+
+    // Try to import SSEManager from @mantiq/realtime — skip silently if unavailable
+    let SSEManager: any
+    let Application: any
+    try {
+      const realtimeModule = await import('@mantiq/realtime')
+      SSEManager = realtimeModule.SSEManager
+      const coreModule = await import('@mantiq/core')
+      Application = coreModule.Application
+    } catch {
+      // @mantiq/realtime is not available — skip silently
+      return
+    }
+
+    const channel = payload.channel ?? `App.User.${notifiable.getKey()}`
+    const event = payload.event
+    const data = payload.data
+
+    try {
+      const sseManager = Application.getInstance().make(SSEManager)
+      sseManager.broadcast(channel, event, data)
+    } catch (error) {
+      throw new NotifyError(`Failed to broadcast notification: ${error instanceof Error ? error.message : String(error)}`, {
+        channel: this.name,
+        notificationType: notification.type,
+        broadcastChannel: channel,
+        event,
+      })
+    }
+  }
+}

package/src/channels/DatabaseChannel.ts

@@ -0,0 +1,45 @@
+import type { NotificationChannel } from '../contracts/Channel.ts'
+import type { Notifiable } from '../contracts/Notifiable.ts'
+import type { Notification } from '../Notification.ts'
+import { DatabaseNotification } from '../models/DatabaseNotification.ts'
+import { NotifyError } from '../errors/NotifyError.ts'
+
+/**
+ * Persists notifications to the database.
+ *
+ * The notification's `toDatabase(notifiable)` method should return a plain
+ * `Record<string, any>` which will be JSON-stringified and stored in the
+ * `data` column of the `notifications` table.
+ */
+export class DatabaseChannel implements NotificationChannel {
+  readonly name = 'database'
+
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    const data = notification.getPayloadFor('database', notifiable)
+    if (data === undefined) return
+
+    const notifiableType = typeof notifiable.getMorphClass === 'function'
+      ? notifiable.getMorphClass()
+      : notifiable.constructor.name
+
+    const notifiableId = notifiable.getKey()
+
+    try {
+      const record = new DatabaseNotification()
+      record.setAttribute('id', notification.id)
+      record.setAttribute('type', notification.type)
+      record.setAttribute('notifiable_type', notifiableType)
+      record.setAttribute('notifiable_id', notifiableId)
+      record.setAttribute('data', typeof data === 'string' ? data : JSON.stringify(data))
+      record.setAttribute('read_at', null)
+      await record.save()
+    } catch (error) {
+      throw new NotifyError(`Failed to store database notification: ${error instanceof Error ? error.message : String(error)}`, {
+        channel: this.name,
+        notificationType: notification.type,
+        notifiableType,
+        notifiableId,
+      })
+    }
+  }
+}

package/src/channels/MailChannel.ts

@@ -0,0 +1,53 @@
+import type { NotificationChannel } from '../contracts/Channel.ts'
+import type { Notifiable } from '../contracts/Notifiable.ts'
+import type { Notification } from '../Notification.ts'
+import { NotifyError } from '../errors/NotifyError.ts'
+
+/**
+ * Delivers notifications via email using the @mantiq/mail package.
+ *
+ * The notification's `toMail(notifiable)` method should return a Mailable instance.
+ * If the mailable has no recipients set, the channel falls back to
+ * `notifiable.routeNotificationFor('mail')` as the recipient address.
+ */
+export class MailChannel implements NotificationChannel {
+  readonly name = 'mail'
+
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    const mailable = notification.getPayloadFor('mail', notifiable)
+    if (!mailable) return
+
+    // Resolve the mail() helper from @mantiq/mail
+    let mail: () => { send(m: any): Promise<any> }
+    try {
+      const mailModule = await import('@mantiq/mail')
+      mail = mailModule.mail as any
+    } catch {
+      throw new NotifyError('MailChannel requires @mantiq/mail to be installed', {
+        channel: this.name,
+        notificationType: notification.type,
+      })
+    }
+
+    // If the mailable has no recipients, use the notifiable's route
+    if (typeof mailable.getTo === 'function' && mailable.getTo().length === 0) {
+      const address = notifiable.routeNotificationFor('mail')
+      if (!address) {
+        throw new NotifyError('No mail recipient: mailable has no recipients and notifiable returned null for mail route', {
+          channel: this.name,
+          notificationType: notification.type,
+        })
+      }
+      mailable.to(address)
+    }
+
+    try {
+      await mail().send(mailable)
+    } catch (error) {
+      throw new NotifyError(`Failed to send mail notification: ${error instanceof Error ? error.message : String(error)}`, {
+        channel: this.name,
+        notificationType: notification.type,
+      })
+    }
+  }
+}

package/src/channels/SlackChannel.ts

@@ -0,0 +1,127 @@
+import type { NotificationChannel } from '../contracts/Channel.ts'
+import type { Notifiable } from '../contracts/Notifiable.ts'
+import type { Notification } from '../Notification.ts'
+import type { SlackConfig } from '../contracts/NotifyConfig.ts'
+import type { SlackMessage } from '../Notification.ts'
+import { NotifyError } from '../errors/NotifyError.ts'
+
+/**
+ * Sends notifications to Slack via webhook URL or the Slack Web API.
+ *
+ * The notification's `toSlack(notifiable)` method should return a `SlackMessage`
+ * with at minimum `text` or `blocks`.
+ *
+ * Two delivery modes:
+ *   1. **Webhook** — POST the payload directly to `config.webhookUrl`
+ *   2. **API** — POST to `https://slack.com/api/chat.postMessage` with a Bearer token
+ *
+ * Uses native `fetch()` — no Slack SDK required.
+ */
+export class SlackChannel implements NotificationChannel {
+  readonly name = 'slack'
+
+  constructor(private readonly config: SlackConfig) {}
+
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    const payload = notification.getPayloadFor('slack', notifiable) as SlackMessage | undefined
+    if (!payload) return
+
+    if (this.config.webhookUrl) {
+      await this.sendViaWebhook(payload, notifiable, notification)
+    } else if (this.config.token) {
+      await this.sendViaApi(payload, notifiable, notification)
+    } else {
+      throw new NotifyError('Slack configuration requires either webhookUrl or token', {
+        channel: this.name,
+        notificationType: notification.type,
+      })
+    }
+  }
+
+  /**
+   * Send via incoming webhook URL.
+   * Simply POSTs the SlackMessage JSON to the webhook URL.
+   */
+  private async sendViaWebhook(
+    payload: SlackMessage,
+    _notifiable: Notifiable,
+    notification: Notification,
+  ): Promise<void> {
+    const body: Record<string, any> = {}
+    if (payload.text) body.text = payload.text
+    if (payload.blocks) body.blocks = payload.blocks
+    if (payload.username) body.username = payload.username
+    if (payload.iconEmoji) body.icon_emoji = payload.iconEmoji
+    if (payload.iconUrl) body.icon_url = payload.iconUrl
+    if (payload.channel) body.channel = payload.channel
+
+    const response = await fetch(this.config.webhookUrl!, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => 'unknown error')
+      throw new NotifyError(`Slack webhook error (${response.status}): ${errorBody}`, {
+        channel: this.name,
+        notificationType: notification.type,
+        statusCode: response.status,
+      })
+    }
+  }
+
+  /**
+   * Send via the Slack Web API (chat.postMessage).
+   * Requires a bot token with `chat:write` scope.
+   */
+  private async sendViaApi(
+    payload: SlackMessage,
+    notifiable: Notifiable,
+    notification: Notification,
+  ): Promise<void> {
+    // Determine channel: payload.channel > notifiable route > error
+    const channel = payload.channel ?? notifiable.routeNotificationFor('slack')
+    if (!channel) {
+      throw new NotifyError('No Slack channel: payload.channel is empty and notifiable returned null for slack route', {
+        channel: this.name,
+        notificationType: notification.type,
+      })
+    }
+
+    const body: Record<string, any> = { channel }
+    if (payload.text) body.text = payload.text
+    if (payload.blocks) body.blocks = payload.blocks
+    if (payload.username) body.username = payload.username
+    if (payload.iconEmoji) body.icon_emoji = payload.iconEmoji
+    if (payload.iconUrl) body.icon_url = payload.iconUrl
+
+    const response = await fetch('https://slack.com/api/chat.postMessage', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.config.token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => 'unknown error')
+      throw new NotifyError(`Slack API HTTP error (${response.status}): ${errorBody}`, {
+        channel: this.name,
+        notificationType: notification.type,
+        statusCode: response.status,
+      })
+    }
+
+    // Slack API returns 200 even on failure — check the `ok` field
+    const result = await response.json().catch(() => null)
+    if (result && !result.ok) {
+      throw new NotifyError(`Slack API error: ${result.error ?? 'unknown error'}`, {
+        channel: this.name,
+        notificationType: notification.type,
+        slackError: result.error,
+      })
+    }
+  }
+}

package/src/channels/SmsChannel.ts

@@ -0,0 +1,146 @@
+import type { NotificationChannel } from '../contracts/Channel.ts'
+import type { Notifiable } from '../contracts/Notifiable.ts'
+import type { Notification } from '../Notification.ts'
+import type { SmsConfig } from '../contracts/NotifyConfig.ts'
+import { NotifyError } from '../errors/NotifyError.ts'
+
+/**
+ * Sends SMS notifications via Twilio or Vonage.
+ *
+ * The notification's `toSms(notifiable)` method should return an `SmsPayload`
+ * with `{ to?, body }`. If `to` is not set, falls back to
+ * `notifiable.routeNotificationFor('sms')`.
+ *
+ * Uses native `fetch()` — no SDK dependencies required.
+ */
+export class SmsChannel implements NotificationChannel {
+  readonly name = 'sms'
+
+  constructor(private readonly config: SmsConfig) {}
+
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    const payload = notification.getPayloadFor('sms', notifiable)
+    if (!payload) return
+
+    const to = payload.to ?? notifiable.routeNotificationFor('sms')
+    if (!to) {
+      throw new NotifyError('No SMS recipient: payload.to is empty and notifiable returned null for sms route', {
+        channel: this.name,
+        notificationType: notification.type,
+      })
+    }
+
+    const body: string = payload.body
+    if (!body) {
+      throw new NotifyError('SMS body is required', {
+        channel: this.name,
+        notificationType: notification.type,
+      })
+    }
+
+    switch (this.config.driver) {
+      case 'twilio':
+        await this.sendViaTwilio(to, body)
+        break
+      case 'vonage':
+        await this.sendViaVonage(to, body)
+        break
+      default:
+        throw new NotifyError(`Unsupported SMS driver: ${this.config.driver}`, {
+          channel: this.name,
+          notificationType: notification.type,
+        })
+    }
+  }
+
+  /**
+   * Send an SMS via the Twilio REST API.
+   * POST https://api.twilio.com/2010-04-01/Accounts/{sid}/Messages.json
+   * with form-encoded body and HTTP Basic auth (sid:token).
+   */
+  private async sendViaTwilio(to: string, body: string): Promise<void> {
+    const twilio = this.config.twilio
+    if (!twilio) {
+      throw new NotifyError('Twilio configuration is missing (twilio.sid, twilio.token, twilio.from)', {
+        channel: this.name,
+        driver: 'twilio',
+      })
+    }
+
+    const url = `https://api.twilio.com/2010-04-01/Accounts/${twilio.sid}/Messages.json`
+    const credentials = btoa(`${twilio.sid}:${twilio.token}`)
+
+    const formData = new URLSearchParams()
+    formData.set('To', to)
+    formData.set('From', twilio.from)
+    formData.set('Body', body)
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Basic ${credentials}`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: formData.toString(),
+    })
+
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => 'unknown error')
+      throw new NotifyError(`Twilio API error (${response.status}): ${errorBody}`, {
+        channel: this.name,
+        driver: 'twilio',
+        statusCode: response.status,
+      })
+    }
+  }
+
+  /**
+   * Send an SMS via the Vonage (Nexmo) REST API.
+   * POST https://rest.nexmo.com/sms/json with JSON body.
+   */
+  private async sendViaVonage(to: string, body: string): Promise<void> {
+    const vonage = this.config.vonage
+    if (!vonage) {
+      throw new NotifyError('Vonage configuration is missing (vonage.apiKey, vonage.apiSecret, vonage.from)', {
+        channel: this.name,
+        driver: 'vonage',
+      })
+    }
+
+    const url = 'https://rest.nexmo.com/sms/json'
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        api_key: vonage.apiKey,
+        api_secret: vonage.apiSecret,
+        from: vonage.from,
+        to,
+        text: body,
+      }),
+    })
+
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => 'unknown error')
+      throw new NotifyError(`Vonage API error (${response.status}): ${errorBody}`, {
+        channel: this.name,
+        driver: 'vonage',
+        statusCode: response.status,
+      })
+    }
+
+    // Vonage returns 200 even on failure — check the response body
+    const result = await response.json().catch(() => null)
+    if (result?.messages?.[0]?.status !== '0') {
+      const errorText = result?.messages?.[0]?.['error-text'] ?? 'Unknown Vonage error'
+      throw new NotifyError(`Vonage delivery failed: ${errorText}`, {
+        channel: this.name,
+        driver: 'vonage',
+        vonageStatus: result?.messages?.[0]?.status,
+      })
+    }
+  }
+}

package/src/channels/WebhookChannel.ts

@@ -0,0 +1,63 @@
+import type { NotificationChannel } from '../contracts/Channel.ts'
+import type { Notifiable } from '../contracts/Notifiable.ts'
+import type { Notification } from '../Notification.ts'
+import type { WebhookPayload } from '../Notification.ts'
+import { NotifyError } from '../errors/NotifyError.ts'
+
+/**
+ * Delivers notifications via outgoing HTTP webhooks.
+ *
+ * The notification's `toWebhook(notifiable)` method should return a
+ * `WebhookPayload` with `{ url, body, method?, headers? }`.
+ *
+ * Sends JSON to the specified URL using native `fetch()`.
+ * Defaults to POST if no method is specified.
+ */
+export class WebhookChannel implements NotificationChannel {
+  readonly name = 'webhook'
+
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    const payload = notification.getPayloadFor('webhook', notifiable) as WebhookPayload | undefined
+    if (!payload) return
+
+    if (!payload.url) {
+      throw new NotifyError('Webhook URL is required', {
+        channel: this.name,
+        notificationType: notification.type,
+      })
+    }
+
+    const method = payload.method ?? 'POST'
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...payload.headers,
+    }
+
+    let response: Response
+    try {
+      response = await fetch(payload.url, {
+        method,
+        headers,
+        body: JSON.stringify(payload.body),
+      })
+    } catch (error) {
+      throw new NotifyError(`Webhook request failed: ${error instanceof Error ? error.message : String(error)}`, {
+        channel: this.name,
+        notificationType: notification.type,
+        url: payload.url,
+        method,
+      })
+    }
+
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => 'unknown error')
+      throw new NotifyError(`Webhook returned ${response.status}: ${errorBody}`, {
+        channel: this.name,
+        notificationType: notification.type,
+        url: payload.url,
+        method,
+        statusCode: response.status,
+      })
+    }
+  }
+}

package/src/commands/MakeNotificationCommand.ts

@@ -0,0 +1,41 @@
+import { GeneratorCommand } from '@mantiq/cli'
+import type { ParsedArgs } from '@mantiq/cli'
+
+export class MakeNotificationCommand extends GeneratorCommand {
+  override name = 'make:notification'
+  override description = 'Create a new notification class'
+  override usage = 'make:notification <name>'
+
+  override directory() { return 'app/Notifications' }
+  override suffix() { return '' }
+
+  override stub(name: string, _args: ParsedArgs): string {
+    const className = name
+
+    return `import { Notification } from '@mantiq/notify'
+import type { Notifiable } from '@mantiq/notify'
+import type { Mailable } from '@mantiq/mail'
+
+export class ${className} extends Notification {
+  constructor(private data: Record<string, any> = {}) { super() }
+
+  via(notifiable: Notifiable): string[] {
+    return ['mail', 'database']
+  }
+
+  toMail(notifiable: Notifiable): Mailable {
+    // Return a Mailable instance
+    // Example: return new ${className}Email(this.data)
+    throw new Error('toMail() not implemented — create a mailable or use markdown')
+  }
+
+  toDatabase(notifiable: Notifiable): Record<string, any> {
+    return {
+      type: '${className}',
+      ...this.data,
+    }
+  }
+}
+`
+  }
+}

package/src/contracts/Channel.ts

@@ -0,0 +1,15 @@
+import type { Notifiable } from './Notifiable.ts'
+import type { Notification } from '../Notification.ts'
+
+/**
+ * The extension protocol for notification channels.
+ *
+ * Third-party packages implement this interface and register via:
+ *   notify().extend('discord', new DiscordChannel())
+ *
+ * Convention: channel named "foo" calls notification.toFoo(notifiable).
+ */
+export interface NotificationChannel {
+  readonly name: string
+  send(notifiable: Notifiable, notification: Notification): Promise<void>
+}

package/src/contracts/Notifiable.ts

@@ -0,0 +1,19 @@
+/**
+ * Notifiable entity — any model that can receive notifications.
+ *
+ * Implement routeNotificationFor() to tell each channel where to deliver:
+ *   - 'mail' → return email address
+ *   - 'sms' → return phone number
+ *   - 'slack' → return Slack channel/webhook
+ *   - 'broadcast' → return channel name (defaults to `App.Model.{id}`)
+ */
+export interface Notifiable {
+  /** Return the routing value for a given channel */
+  routeNotificationFor(channel: string): string | null
+
+  /** Get the entity's primary key */
+  getKey(): any
+
+  /** Get the entity's type name (e.g., 'User') */
+  getMorphClass?(): string
+}

package/src/contracts/NotifyConfig.ts

@@ -0,0 +1,21 @@
+export interface SmsConfig {
+  driver: 'twilio' | 'vonage'
+  twilio?: { sid: string; token: string; from: string }
+  vonage?: { apiKey: string; apiSecret: string; from: string }
+}
+
+export interface SlackConfig {
+  webhookUrl?: string
+  token?: string
+}
+
+export interface NotifyConfig {
+  channels?: {
+    sms?: SmsConfig
+    slack?: SlackConfig
+  }
+}
+
+export const DEFAULT_CONFIG: NotifyConfig = {
+  channels: {},
+}

package/src/errors/NotifyError.ts

@@ -0,0 +1,7 @@
+import { MantiqError } from '@mantiq/core'
+
+export class NotifyError extends MantiqError {
+  constructor(message: string, context?: Record<string, any>) {
+    super(message, context)
+  }
+}

package/src/events/NotificationEvents.ts

@@ -0,0 +1,27 @@
+import type { Notifiable } from '../contracts/Notifiable.ts'
+import type { Notification } from '../Notification.ts'
+
+export class NotificationSending {
+  constructor(
+    public readonly notifiable: Notifiable,
+    public readonly notification: Notification,
+    public readonly channel: string,
+  ) {}
+}
+
+export class NotificationSent {
+  constructor(
+    public readonly notifiable: Notifiable,
+    public readonly notification: Notification,
+    public readonly channel: string,
+  ) {}
+}
+
+export class NotificationFailed {
+  constructor(
+    public readonly notifiable: Notifiable,
+    public readonly notification: Notification,
+    public readonly channel: string,
+    public readonly error: Error,
+  ) {}
+}

package/src/helpers/notify.ts

@@ -0,0 +1,8 @@
+import { Application } from '@mantiq/core'
+import type { NotificationManager } from '../NotificationManager.ts'
+
+export const NOTIFY_MANAGER = Symbol('NotificationManager')
+
+export function notify(): NotificationManager {
+  return Application.getInstance().make<NotificationManager>(NOTIFY_MANAGER)
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+// ── Contracts ────────────────────────────────────────────────────────────────
+export type { NotificationChannel } from './contracts/Channel.ts'
+export type { Notifiable } from './contracts/Notifiable.ts'
+export type { NotifyConfig, SmsConfig, SlackConfig } from './contracts/NotifyConfig.ts'
+
+// ── Core ─────────────────────────────────────────────────────────────────────
+export { Notification } from './Notification.ts'
+export type { SlackMessage, BroadcastPayload, SmsPayload, WebhookPayload } from './Notification.ts'
+export { NotificationManager } from './NotificationManager.ts'
+
+// ── Channels ─────────────────────────────────────────────────────────────────
+export { MailChannel } from './channels/MailChannel.ts'
+export { DatabaseChannel } from './channels/DatabaseChannel.ts'
+export { BroadcastChannel } from './channels/BroadcastChannel.ts'
+export { SmsChannel } from './channels/SmsChannel.ts'
+export { SlackChannel } from './channels/SlackChannel.ts'
+export { WebhookChannel } from './channels/WebhookChannel.ts'
+
+// ── Models ───────────────────────────────────────────────────────────────────
+export { DatabaseNotification } from './models/DatabaseNotification.ts'
+
+// ── Events ───────────────────────────────────────────────────────────────────
+export { NotificationSending, NotificationSent, NotificationFailed } from './events/NotificationEvents.ts'
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+export { notify, NOTIFY_MANAGER } from './helpers/notify.ts'
+
+// ── Service Provider ─────────────────────────────────────────────────────────
+export { NotificationServiceProvider } from './NotificationServiceProvider.ts'
+
+// ── Testing ──────────────────────────────────────────────────────────────────
+export { NotificationFake } from './testing/NotificationFake.ts'
+
+// ── Errors ───────────────────────────────────────────────────────────────────
+export { NotifyError } from './errors/NotifyError.ts'
+
+// ── Commands ─────────────────────────────────────────────────────────────────
+export { MakeNotificationCommand } from './commands/MakeNotificationCommand.ts'

package/src/jobs/SendNotificationJob.ts

@@ -0,0 +1,20 @@
+import { Job } from '@mantiq/queue'
+import type { Notifiable } from '../contracts/Notifiable.ts'
+import type { Notification } from '../Notification.ts'
+
+export class SendNotificationJob extends Job {
+  override name = 'notify:send'
+  override tries = 3
+
+  constructor(
+    private notifiable: Notifiable,
+    private notification: Notification,
+  ) {
+    super()
+  }
+
+  override async handle(): Promise<void> {
+    const { notify } = await import('../helpers/notify.ts')
+    await notify().sendNow(this.notifiable, this.notification)
+  }
+}

package/src/migrations/CreateNotificationsTable.ts

@@ -0,0 +1,20 @@
+import { Migration } from '@mantiq/database'
+import type { SchemaBuilder } from '@mantiq/database'
+
+export default class CreateNotificationsTable extends Migration {
+  override async up(schema: SchemaBuilder) {
+    await schema.create('notifications', (t) => {
+      t.string('id', 36).primary()
+      t.string('type', 255)
+      t.string('notifiable_type', 255)
+      t.integer('notifiable_id').unsigned()
+      t.text('data')
+      t.timestamp('read_at').nullable()
+      t.timestamps()
+    })
+  }
+
+  override async down(schema: SchemaBuilder) {
+    await schema.dropIfExists('notifications')
+  }
+}

package/src/models/DatabaseNotification.ts

@@ -0,0 +1,29 @@
+import { Model } from '@mantiq/database'
+
+export class DatabaseNotification extends Model {
+  static override table = 'notifications'
+  static override primaryKey = 'id'
+  static override fillable = ['id', 'type', 'notifiable_type', 'notifiable_id', 'data', 'read_at']
+  static override timestamps = true
+  static override casts = { data: 'json' as const }
+
+  get isRead(): boolean {
+    return this.getAttribute('read_at') != null
+  }
+
+  get isUnread(): boolean {
+    return !this.isRead
+  }
+
+  async markAsRead(): Promise<this> {
+    this.setAttribute('read_at', new Date().toISOString())
+    await this.save()
+    return this
+  }
+
+  async markAsUnread(): Promise<this> {
+    this.setAttribute('read_at', null)
+    await this.save()
+    return this
+  }
+}

package/src/testing/NotificationFake.ts

@@ -0,0 +1,107 @@
+import type { Notifiable } from '../contracts/Notifiable.ts'
+import type { Notification } from '../Notification.ts'
+
+interface SentRecord {
+  notifiable: Notifiable
+  notification: Notification
+  channels: string[]
+}
+
+/**
+ * In-memory notification fake for testing.
+ *
+ * @example
+ *   const fake = new NotificationFake()
+ *   // ... run code that sends notifications ...
+ *   fake.assertSentTo(user, OrderShipped)
+ *   fake.assertNotSentTo(user, InvoiceEmail)
+ *   fake.assertCount(OrderShipped, 2)
+ */
+export class NotificationFake {
+  private _sent: SentRecord[] = []
+
+  /** Record a sent notification (called by test harness) */
+  async send(notifiable: Notifiable | Notifiable[], notification: Notification): Promise<void> {
+    const notifiables = Array.isArray(notifiable) ? notifiable : [notifiable]
+    for (const n of notifiables) {
+      this._sent.push({
+        notifiable: n,
+        notification,
+        channels: notification.via(n),
+      })
+    }
+  }
+
+  async sendNow(notifiable: Notifiable, notification: Notification): Promise<void> {
+    await this.send(notifiable, notification)
+  }
+
+  // ── Assertions ──────────────────────────────────────────────────────────
+
+  assertSentTo(notifiable: Notifiable, notificationClass: new (...args: any[]) => Notification, count?: number): void {
+    const matches = this._sent.filter(r =>
+      r.notifiable.getKey() === notifiable.getKey() &&
+      r.notification instanceof notificationClass
+    )
+    if (matches.length === 0) {
+      throw new Error(`Expected [${notificationClass.name}] to be sent to notifiable [${notifiable.getKey()}], but it was not.`)
+    }
+    if (count !== undefined && matches.length !== count) {
+      throw new Error(`Expected [${notificationClass.name}] to be sent ${count} time(s) to [${notifiable.getKey()}], but was sent ${matches.length} time(s).`)
+    }
+  }
+
+  assertNotSentTo(notifiable: Notifiable, notificationClass: new (...args: any[]) => Notification): void {
+    const matches = this._sent.filter(r =>
+      r.notifiable.getKey() === notifiable.getKey() &&
+      r.notification instanceof notificationClass
+    )
+    if (matches.length > 0) {
+      throw new Error(`Expected [${notificationClass.name}] NOT to be sent to [${notifiable.getKey()}], but it was sent ${matches.length} time(s).`)
+    }
+  }
+
+  assertSent(notificationClass: new (...args: any[]) => Notification, count?: number): void {
+    const matches = this._sent.filter(r => r.notification instanceof notificationClass)
+    if (matches.length === 0) {
+      throw new Error(`Expected [${notificationClass.name}] to be sent, but it was not.`)
+    }
+    if (count !== undefined && matches.length !== count) {
+      throw new Error(`Expected [${notificationClass.name}] to be sent ${count} time(s), but was sent ${matches.length} time(s).`)
+    }
+  }
+
+  assertNothingSent(): void {
+    if (this._sent.length > 0) {
+      const types = [...new Set(this._sent.map(r => r.notification.type))].join(', ')
+      throw new Error(`Expected no notifications sent, but ${this._sent.length} were sent: ${types}`)
+    }
+  }
+
+  assertCount(notificationClass: new (...args: any[]) => Notification, expected: number): void {
+    this.assertSent(notificationClass, expected)
+  }
+
+  assertSentToVia(notifiable: Notifiable, notificationClass: new (...args: any[]) => Notification, channel: string): void {
+    const matches = this._sent.filter(r =>
+      r.notifiable.getKey() === notifiable.getKey() &&
+      r.notification instanceof notificationClass &&
+      r.channels.includes(channel)
+    )
+    if (matches.length === 0) {
+      throw new Error(`Expected [${notificationClass.name}] to be sent to [${notifiable.getKey()}] via [${channel}], but it was not.`)
+    }
+  }
+
+  // ── Inspection ──────────────────────────────────────────────────────────
+
+  sent(): SentRecord[] { return [...this._sent] }
+
+  sentTo(notifiable: Notifiable): SentRecord[] {
+    return this._sent.filter(r => r.notifiable.getKey() === notifiable.getKey())
+  }
+
+  reset(): void {
+    this._sent = []
+  }
+}