@mantiq/notify 0.5.21 → 0.5.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantiq/notify",
-  "version": "0.5.21",
+  "version": "0.5.23",
   "description": "Multi-channel notifications — mail, database, broadcast, SMS, Slack, webhook",
   "type": "module",
   "license": "MIT",

package/src/NotificationManager.ts

@@ -4,6 +4,7 @@ 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 { NotificationSent, NotificationFailed } from './events/NotificationEvents.ts'
 import { MailChannel } from './channels/MailChannel.ts'
 import { DatabaseChannel } from './channels/DatabaseChannel.ts'
 import { BroadcastChannel } from './channels/BroadcastChannel.ts'
@@ -27,10 +28,22 @@ import { FirebaseChannel } from './channels/FirebaseChannel.ts'
  *   await notify().send(user, new OrderShipped(order))
  *   await notify().send([user1, user2], new OrderShipped(order))
  */
+export interface DeliveryLogEntry {
+  id: string
+  notification: string
+  channel: string
+  recipient: string
+  status: 'sent' | 'failed'
+  sentAt: Date
+  error?: string | undefined
+}
+
 export class NotificationManager {
   private _channels = new Map<string, NotificationChannel>()
   private _factories = new Map<string, () => NotificationChannel>()
   private config: NotifyConfig
+  private _deliveryLog: DeliveryLogEntry[] = []
+  private _eventObservers: ((event: NotificationSent | NotificationFailed) => void)[] = []
 
   constructor(config?: Partial<NotifyConfig>) {
     this.config = { ...DEFAULT_CONFIG, ...config }
@@ -53,14 +66,14 @@ export class NotificationManager {
     }
   }
 
-  /** Send immediately, bypassing queue */
+  /** Send immediately, bypassing queue. Uses retry for each channel. */
   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)
+        await this.sendWithRetry(notifiable, notification, channel, 3)
       } catch (err) {
         // Log but don't fail other channels
         console.error(`[Mantiq] Notification channel "${channelName}" failed:`, (err as Error).message)
@@ -68,6 +81,78 @@ export class NotificationManager {
     }
   }
 
+  /**
+   * Send a notification through a channel with retry logic.
+   * Records delivery status and emits events.
+   */
+  async sendWithRetry(
+    notifiable: Notifiable,
+    notification: Notification,
+    channel: NotificationChannel,
+    maxRetries: number = 1,
+  ): Promise<void> {
+    let lastError: Error | undefined
+
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        await channel.send(notifiable, notification)
+
+        // Success — record and emit
+        this._deliveryLog.push({
+          id: notification.id,
+          notification: notification.constructor.name,
+          channel: channel.name,
+          recipient: String(notifiable.getKey()),
+          status: 'sent',
+          sentAt: new Date(),
+        })
+
+        this.emitEvent(new NotificationSent(notifiable, notification, channel.name))
+        return
+      } catch (err) {
+        lastError = err as Error
+      }
+    }
+
+    // All retries exhausted — record failure and emit
+    this._deliveryLog.push({
+      id: notification.id,
+      notification: notification.constructor.name,
+      channel: channel.name,
+      recipient: String(notifiable.getKey()),
+      status: 'failed',
+      sentAt: new Date(),
+      error: lastError?.message,
+    })
+
+    this.emitEvent(new NotificationFailed(notifiable, notification, channel.name, lastError!))
+    throw lastError!
+  }
+
+  // ── Delivery Log ──────────────────────────────────────────────────────
+
+  /** Get all delivery log entries. */
+  deliveryLog(): DeliveryLogEntry[] {
+    return [...this._deliveryLog]
+  }
+
+  /** Get deliveries for a specific notification ID. */
+  deliveriesFor(notificationId: string): DeliveryLogEntry[] {
+    return this._deliveryLog.filter((e) => e.id === notificationId)
+  }
+
+  /** Clear the delivery log. */
+  clearDeliveryLog(): void {
+    this._deliveryLog = []
+  }
+
+  // ── Delivery Events ───────────────────────────────────────────────────
+
+  /** Register an observer for delivery events. */
+  onDeliveryEvent(observer: (event: NotificationSent | NotificationFailed) => void): void {
+    this._eventObservers.push(observer)
+  }
+
   /** Get a channel by name */
   channel(name: string): NotificationChannel {
     if (this._channels.has(name)) return this._channels.get(name)!
@@ -125,6 +210,16 @@ export class NotificationManager {
     if (ch?.firebase) this._factories.set('firebase', () => new FirebaseChannel(ch.firebase!))
   }
 
+  private emitEvent(event: NotificationSent | NotificationFailed): void {
+    for (const observer of this._eventObservers) {
+      try {
+        observer(event)
+      } catch {
+        // Observer errors must not break delivery
+      }
+    }
+  }
+
   private async queueNotification(notifiable: Notifiable, notification: Notification): Promise<void> {
     try {
       const { dispatch } = await import('@mantiq/queue')

package/src/channels/WebhookChannel.ts

@@ -16,6 +16,85 @@ import { NotifyError } from '../errors/NotifyError.ts'
 export class WebhookChannel implements NotificationChannel {
   readonly name = 'webhook'
 
+  /**
+   * Security: validate webhook URL to prevent SSRF attacks.
+   * Rejects private/reserved IP ranges, localhost, link-local, and non-http(s) schemes
+   * so that attackers cannot target internal services (e.g. cloud metadata at 169.254.169.254).
+   */
+  private validateUrl(url: string): void {
+    let parsed: URL
+    try {
+      parsed = new URL(url)
+    } catch {
+      throw new NotifyError('Webhook URL is not a valid URL', {
+        channel: this.name,
+        url,
+      })
+    }
+
+    // Only allow http and https
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new NotifyError(`Webhook URL scheme "${parsed.protocol}" is not allowed — only http and https`, {
+        channel: this.name,
+        url,
+      })
+    }
+
+    const hostname = parsed.hostname
+
+    // Reject IPv6 addresses in brackets
+    const ipv6Match = hostname.match(/^\[(.+)\]$/)
+    if (ipv6Match) {
+      const ipv6 = ipv6Match[1]!.toLowerCase()
+      // Reject loopback (::1), link-local (fe80::), unique-local (fc00::/7 = fc and fd)
+      if (
+        ipv6 === '::1' ||
+        ipv6.startsWith('fe80:') ||
+        ipv6.startsWith('fc') ||
+        ipv6.startsWith('fd')
+      ) {
+        throw new NotifyError('Webhook URL targets a private/reserved network address', {
+          channel: this.name,
+          url,
+        })
+      }
+    }
+
+    // Reject known private/reserved IPv4 ranges and localhost
+    const lower = hostname.toLowerCase()
+    if (
+      lower === 'localhost' ||
+      lower.endsWith('.localhost') ||
+      lower === '[::1]'
+    ) {
+      throw new NotifyError('Webhook URL targets a private/reserved network address', {
+        channel: this.name,
+        url,
+      })
+    }
+
+    // Check IPv4-like hostnames
+    const ipv4Parts = hostname.split('.')
+    if (ipv4Parts.length === 4 && ipv4Parts.every((p) => /^\d{1,3}$/.test(p))) {
+      const octets = ipv4Parts.map(Number)
+      const [a, b] = octets as [number, number, number, number]
+
+      if (
+        a === 127 ||                           // 127.0.0.0/8 — loopback
+        a === 10 ||                            // 10.0.0.0/8 — private
+        (a === 172 && b >= 16 && b <= 31) ||   // 172.16.0.0/12 — private
+        (a === 192 && b === 168) ||            // 192.168.0.0/16 — private
+        (a === 169 && b === 254) ||            // 169.254.0.0/16 — link-local (AWS metadata)
+        a === 0                                // 0.0.0.0/8
+      ) {
+        throw new NotifyError('Webhook URL targets a private/reserved network address', {
+          channel: this.name,
+          url,
+        })
+      }
+    }
+  }
+
   async send(notifiable: Notifiable, notification: Notification): Promise<void> {
     const payload = notification.getPayloadFor('webhook', notifiable) as WebhookPayload | undefined
     if (!payload) return
@@ -27,6 +106,9 @@ export class WebhookChannel implements NotificationChannel {
       })
     }
 
+    // Security: validate URL before making the request to prevent SSRF
+    this.validateUrl(payload.url)
+
     const method = payload.method ?? 'POST'
     const headers: Record<string, string> = {
       'Content-Type': 'application/json',

package/src/index.ts

@@ -7,6 +7,7 @@ export type { NotifyConfig, SmsConfig, SlackConfig, TelegramConfig, WhatsAppConf
 export { Notification } from './Notification.ts'
 export type { SlackMessage, BroadcastPayload, SmsPayload, WebhookPayload } from './Notification.ts'
 export { NotificationManager } from './NotificationManager.ts'
+export type { DeliveryLogEntry } from './NotificationManager.ts'
 
 // ── Channels ─────────────────────────────────────────────────────────────────
 export { MailChannel } from './channels/MailChannel.ts'