@gravito/flare 3.0.3 → 3.3.0

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -25,9 +35,12 @@ __export(index_exports, {
   MailChannel: () => MailChannel,
   Notification: () => Notification,
   NotificationManager: () => NotificationManager,
+  NotificationMetricsCollector: () => NotificationMetricsCollector,
   OrbitFlare: () => OrbitFlare,
   SlackChannel: () => SlackChannel,
-  SmsChannel: () => SmsChannel
+  SmsChannel: () => SmsChannel,
+  TemplatedNotification: () => TemplatedNotification,
+  toPrometheusFormat: () => toPrometheusFormat
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -167,48 +180,145 @@ var SmsChannel = class {
   /**
    * Send SMS via AWS SNS.
    */
-  async sendViaAwsSns(_message) {
-    throw new Error("AWS SNS SMS provider not yet implemented. Please install @aws-sdk/client-sns");
+  async sendViaAwsSns(message) {
+    let SNSClient;
+    let PublishCommand;
+    try {
+      const awsSns = await import("@aws-sdk/client-sns");
+      SNSClient = awsSns.SNSClient;
+      PublishCommand = awsSns.PublishCommand;
+    } catch {
+      throw new Error(
+        "AWS SNS SMS requires @aws-sdk/client-sns. Install it with: bun add @aws-sdk/client-sns"
+      );
+    }
+    const client = new SNSClient({
+      region: this.config.region || "us-east-1",
+      credentials: this.config.accessKeyId && this.config.secretAccessKey ? {
+        accessKeyId: this.config.accessKeyId,
+        secretAccessKey: this.config.secretAccessKey
+      } : void 0
+      // Use environment variables or IAM role
+    });
+    const command = new PublishCommand({
+      PhoneNumber: message.to,
+      Message: message.message,
+      MessageAttributes: {
+        "AWS.SNS.SMS.SenderID": {
+          DataType: "String",
+          StringValue: message.from || this.config.from || "GRAVITO"
+        },
+        "AWS.SNS.SMS.SMSType": {
+          DataType: "String",
+          StringValue: "Transactional"
+          // Or 'Promotional'
+        }
+      }
+    });
+    try {
+      await client.send(command);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      throw new Error(`Failed to send SMS via AWS SNS: ${err.message}`);
+    }
   }
 };
 
-// src/Notification.ts
-var Notification = class {
-  /**
-   * Get mail message (optional).
-   * Implement this if the notification will be sent via the mail channel.
-   */
-  toMail(_notifiable) {
-    throw new Error("toMail method not implemented");
+// src/metrics/exporters/PrometheusExporter.ts
+function toPrometheusFormat(summary) {
+  const lines = [];
+  lines.push(`# HELP notification_total Total notifications sent`);
+  lines.push(`# TYPE notification_total counter`);
+  lines.push(`notification_total ${summary.totalSent}`);
+  lines.push(`# HELP notification_success_total Successful notifications`);
+  lines.push(`# TYPE notification_success_total counter`);
+  lines.push(`notification_success_total ${summary.totalSuccess}`);
+  lines.push(`# HELP notification_failed_total Failed notifications`);
+  lines.push(`# TYPE notification_failed_total counter`);
+  lines.push(`notification_failed_total ${summary.totalFailed}`);
+  lines.push(`# HELP notification_channel_total Notifications by channel`);
+  lines.push(`# TYPE notification_channel_total counter`);
+  for (const [channel, stats] of Object.entries(summary.byChannel)) {
+    lines.push(`notification_channel_total{channel="${channel}",status="success"} ${stats.success}`);
+    lines.push(`notification_channel_total{channel="${channel}",status="failed"} ${stats.failed}`);
   }
-  /**
-   * Get database notification (optional).
-   * Implement this if the notification will be stored via the database channel.
-   */
-  toDatabase(_notifiable) {
-    throw new Error("toDatabase method not implemented");
+  lines.push(`# HELP notification_duration_avg Average notification duration in ms`);
+  lines.push(`# TYPE notification_duration_avg gauge`);
+  lines.push(`notification_duration_avg ${summary.avgDuration.toFixed(2)}`);
+  return lines.join("\n");
+}
+
+// src/metrics/NotificationMetrics.ts
+var NotificationMetricsCollector = class {
+  metrics = [];
+  maxHistory;
+  constructor(maxHistory = 1e4) {
+    this.maxHistory = maxHistory;
   }
-  /**
-   * Get broadcast notification (optional).
-   * Implement this if the notification will be sent via the broadcast channel.
-   */
-  toBroadcast(_notifiable) {
-    throw new Error("toBroadcast method not implemented");
+  record(metric) {
+    this.metrics.push(metric);
+    if (this.metrics.length > this.maxHistory) {
+      this.metrics = this.metrics.slice(-this.maxHistory);
+    }
   }
-  /**
-   * Get Slack message (optional).
-   * Implement this if the notification will be sent via the Slack channel.
-   */
-  toSlack(_notifiable) {
-    throw new Error("toSlack method not implemented");
+  getSummary(since) {
+    let filtered = this.metrics;
+    if (since) {
+      filtered = this.metrics.filter((m) => m.timestamp >= since);
+    }
+    const byChannel = {};
+    const byNotification = {};
+    for (const metric of filtered) {
+      if (!byChannel[metric.channel]) {
+        byChannel[metric.channel] = { sent: 0, success: 0, failed: 0, avgDuration: 0 };
+      }
+      byChannel[metric.channel].sent++;
+      if (metric.success) {
+        byChannel[metric.channel].success++;
+      } else {
+        byChannel[metric.channel].failed++;
+      }
+      if (!byNotification[metric.notification]) {
+        byNotification[metric.notification] = { sent: 0, success: 0, failed: 0, avgDuration: 0 };
+      }
+      byNotification[metric.notification].sent++;
+      if (metric.success) {
+        byNotification[metric.notification].success++;
+      } else {
+        byNotification[metric.notification].failed++;
+      }
+    }
+    for (const channel of Object.keys(byChannel)) {
+      const channelMetrics = filtered.filter((m) => m.channel === channel);
+      byChannel[channel].avgDuration = channelMetrics.reduce((sum, m) => sum + m.duration, 0) / channelMetrics.length;
+    }
+    for (const notification of Object.keys(byNotification)) {
+      const notificationMetrics = filtered.filter((m) => m.notification === notification);
+      byNotification[notification].avgDuration = notificationMetrics.reduce((sum, m) => sum + m.duration, 0) / notificationMetrics.length;
+    }
+    const successMetrics = filtered.filter((m) => m.success);
+    return {
+      totalSent: filtered.length,
+      totalSuccess: successMetrics.length,
+      totalFailed: filtered.length - successMetrics.length,
+      avgDuration: filtered.length > 0 ? filtered.reduce((sum, m) => sum + m.duration, 0) / filtered.length : 0,
+      byChannel,
+      byNotification
+    };
   }
-  /**
-   * Get SMS message (optional).
-   * Implement this if the notification will be sent via the SMS channel.
-   */
-  toSms(_notifiable) {
-    throw new Error("toSms method not implemented");
+  getRecentFailures(limit = 10) {
+    return this.metrics.filter((m) => !m.success).slice(-limit);
+  }
+  getSlowNotifications(threshold, limit = 10) {
+    return this.metrics.filter((m) => m.duration > threshold).slice(-limit);
+  }
+  clear() {
+    this.metrics = [];
   }
+};
+
+// src/Notification.ts
+var Notification = class {
   /**
    * Check whether this notification should be queued.
    */
@@ -231,6 +341,107 @@ var Notification = class {
   }
 };
 
+// src/utils/retry.ts
+var DEFAULT_RETRY_OPTIONS = {
+  maxAttempts: 3,
+  baseDelay: 1e3,
+  backoff: "exponential",
+  maxDelay: 3e4
+};
+async function withRetry(fn, options = {}) {
+  const config = { ...DEFAULT_RETRY_OPTIONS, ...options };
+  let lastError;
+  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (config.shouldRetry && !config.shouldRetry(lastError, attempt)) {
+        throw lastError;
+      }
+      if (attempt === config.maxAttempts) {
+        break;
+      }
+      const delay = calculateDelay(attempt, config);
+      config.onRetry?.(lastError, attempt, delay);
+      await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+function calculateDelay(attempt, config) {
+  let delay;
+  switch (config.backoff) {
+    case "fixed":
+      delay = config.baseDelay;
+      break;
+    case "linear":
+      delay = config.baseDelay * attempt;
+      break;
+    case "exponential":
+      delay = config.baseDelay * 2 ** (attempt - 1);
+      break;
+  }
+  const jitter = delay * 0.1 * Math.random();
+  delay = delay + jitter;
+  return Math.min(delay, config.maxDelay);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryableError(error) {
+  const message = error.message.toLowerCase();
+  if (message.includes("network") || message.includes("timeout")) {
+    return true;
+  }
+  if (message.includes("rate limit") || message.includes("too many requests")) {
+    return true;
+  }
+  if (message.includes("503") || message.includes("service unavailable")) {
+    return true;
+  }
+  return false;
+}
+
+// src/utils/serialization.ts
+function deepSerialize(obj, seen = /* @__PURE__ */ new WeakSet()) {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if (seen.has(obj)) {
+    return "[Circular]";
+  }
+  seen.add(obj);
+  if (obj instanceof Date) {
+    return { __type: "Date", value: obj.toISOString() };
+  }
+  if (obj instanceof Map) {
+    return {
+      __type: "Map",
+      value: Array.from(obj.entries()).map(([k, v]) => [
+        deepSerialize(k, seen),
+        deepSerialize(v, seen)
+      ])
+    };
+  }
+  if (obj instanceof Set) {
+    return {
+      __type: "Set",
+      value: Array.from(obj).map((v) => deepSerialize(v, seen))
+    };
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => deepSerialize(item, seen));
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (!key.startsWith("_") && typeof value !== "function") {
+      result[key] = deepSerialize(value, seen);
+    }
+  }
+  return result;
+}
+
 // src/NotificationManager.ts
 var NotificationManager = class {
   constructor(core) {
@@ -244,6 +455,25 @@ var NotificationManager = class {
    * Queue manager (optional, injected by `orbit-queue`).
    */
   queueManager;
+  metrics;
+  /**
+   * Enable metrics collection.
+   */
+  enableMetrics(maxHistory = 1e4) {
+    this.metrics = new NotificationMetricsCollector(maxHistory);
+  }
+  /**
+   * Get metrics summary.
+   */
+  getMetrics(since) {
+    return this.metrics?.getSummary(since);
+  }
+  /**
+   * Get recent failures.
+   */
+  getRecentFailures(limit = 10) {
+    return this.metrics?.getRecentFailures(limit) ?? [];
+  }
   /**
    * Register a notification channel.
    *
@@ -266,16 +496,29 @@ var NotificationManager = class {
    *
    * @param notifiable - The recipient of the notification.
    * @param notification - The notification instance.
-   * @returns A promise that resolves when the notification is sent or queued.
+   * @param options - Options for sending.
+   * @returns A promise that resolves to the notification result.
    *
    * @example
    * ```typescript
-   * await notificationManager.send(user, new InvoicePaid(invoice))
+   * const result = await notificationManager.send(user, new InvoicePaid(invoice))
+   * if (!result.allSuccess) { ... }
    * ```
    */
-  async send(notifiable, notification) {
+  async send(notifiable, notification, options = {}) {
     const channels = notification.via(notifiable);
+    const startTime = Date.now();
+    await this.core.hooks.emit("notification:sending", {
+      notification,
+      notifiable,
+      channels
+    });
     if (notification.shouldQueue() && this.queueManager) {
+      await this.core.hooks.emit("notification:queued", {
+        notification,
+        notifiable,
+        channels
+      });
       const queueConfig = notification.getQueueConfig();
       const queueJob = {
         type: "notification",
@@ -294,33 +537,281 @@ var NotificationManager = class {
         queueConfig.connection,
         queueConfig.delay
       );
-      return;
+      return {
+        notification: notification.constructor.name,
+        notifiable: notifiable.getNotifiableId(),
+        results: [{ success: true, channel: "queue" }],
+        allSuccess: true,
+        timestamp: /* @__PURE__ */ new Date()
+      };
+    }
+    const results = await this.sendNow(notifiable, notification, channels, options);
+    const totalDuration = Date.now() - startTime;
+    await this.core.hooks.emit("notification:sent", {
+      notification,
+      notifiable,
+      results,
+      allSuccess: results.every((r) => r.success),
+      totalDuration
+    });
+    if (options.throwOnError) {
+      const errors = results.filter((r) => !r.success && r.error).map((r) => r.error);
+      if (errors.length > 0) {
+        throw new AggregateError(errors, `Notification failed on ${errors.length} channel(s)`);
+      }
     }
-    await this.sendNow(notifiable, notification, channels);
+    return {
+      notification: notification.constructor.name,
+      notifiable: notifiable.getNotifiableId(),
+      results,
+      allSuccess: results.every((r) => r.success),
+      timestamp: /* @__PURE__ */ new Date()
+    };
   }
   /**
-   * Send immediately (without queue).
+   * Batch send notification to multiple recipients.
+   *
+   * @param notifiables - List of recipients.
+   * @param notification - The notification instance.
+   * @param options - Options for sending.
+   * @returns A promise that resolves to the batch result.
+   */
+  async sendBatch(notifiables, notification, options = {}) {
+    const { batchConcurrency = 10 } = options;
+    const startTime = Date.now();
+    const results = [];
+    await this.core.hooks.emit("notification:batch:start", {
+      notification,
+      count: notifiables.length
+    });
+    for (let i = 0; i < notifiables.length; i += batchConcurrency) {
+      const batch = notifiables.slice(i, i + batchConcurrency);
+      const batchPromises = batch.map((notifiable) => this.send(notifiable, notification, options));
+      const batchResults = await Promise.all(batchPromises);
+      results.push(...batchResults);
+    }
+    const duration = Date.now() - startTime;
+    const successCount = results.filter((r) => r.allSuccess).length;
+    await this.core.hooks.emit("notification:batch:complete", {
+      notification,
+      total: notifiables.length,
+      success: successCount,
+      failed: notifiables.length - successCount,
+      duration
+    });
+    return {
+      total: notifiables.length,
+      success: successCount,
+      failed: notifiables.length - successCount,
+      results,
+      duration
+    };
+  }
+  /**
+   * Batch send notification to multiple recipients (streaming).
    *
-   * @param notifiable - The recipient.
-   * @param notification - The notification.
-   * @param channels - The list of channels to send via.
+   * @param notifiables - AsyncIterable or Iterable of recipients.
+   * @param notification - The notification instance.
+   * @param options - Options for sending.
+   * @yields Notification results as they are processed.
    */
-  async sendNow(notifiable, notification, channels) {
+  async *sendBatchStream(notifiables, notification, options = {}) {
+    const { batchSize = 10 } = options;
+    let batch = [];
+    for await (const notifiable of notifiables) {
+      batch.push(notifiable);
+      if (batch.length >= batchSize) {
+        const promises = batch.map((n) => this.send(n, notification, options));
+        const results = await Promise.all(promises);
+        for (const result of results) {
+          yield result;
+        }
+        batch = [];
+      }
+    }
+    if (batch.length > 0) {
+      const promises = batch.map((n) => this.send(n, notification, options));
+      const results = await Promise.all(promises);
+      for (const result of results) {
+        yield result;
+      }
+    }
+  }
+  /**
+   * Send immediately (without queue).
+   */
+  async sendNow(notifiable, notification, channels, options = {}) {
+    const { parallel = true, concurrency } = options;
+    if (!parallel) {
+      return this.sendSequential(notifiable, notification, channels, options);
+    }
+    if (concurrency && concurrency > 0) {
+      return this.sendWithConcurrencyLimit(notifiable, notification, channels, concurrency, options);
+    }
+    return this.sendParallel(notifiable, notification, channels, options);
+  }
+  async sendSequential(notifiable, notification, channels, options) {
+    const results = [];
     for (const channelName of channels) {
-      const channel = this.channels.get(channelName);
-      if (!channel) {
-        this.core.logger.warn(`[NotificationManager] Channel '${channelName}' not found, skipping`);
-        continue;
+      results.push(await this.sendToChannel(notifiable, notification, channelName, options?.retry));
+    }
+    return results;
+  }
+  async sendParallel(notifiable, notification, channels, options) {
+    const promises = channels.map(
+      (channelName) => this.sendToChannel(notifiable, notification, channelName, options?.retry)
+    );
+    return Promise.all(promises);
+  }
+  async sendWithConcurrencyLimit(notifiable, notification, channels, concurrency, options) {
+    return this.processWithConcurrency(
+      channels,
+      (channel) => this.sendToChannel(notifiable, notification, channel, options?.retry),
+      concurrency
+    );
+  }
+  async processWithConcurrency(items, handler, concurrency) {
+    const finalResults = [];
+    const pool = /* @__PURE__ */ new Set();
+    for (const item of items) {
+      const p = handler(item).then((res) => {
+        finalResults.push(res);
+      });
+      pool.add(p);
+      p.finally(() => pool.delete(p));
+      if (pool.size >= concurrency) {
+        await Promise.race(pool);
       }
-      try {
-        await channel.send(notification, notifiable);
-      } catch (error) {
-        this.core.logger.error(
-          `[NotificationManager] Failed to send notification via '${channelName}':`,
-          error
+    }
+    await Promise.all(pool);
+    return finalResults;
+  }
+  async sendToChannel(notifiable, notification, channelName, retryConfig) {
+    const channel = this.channels.get(channelName);
+    const startTime = Date.now();
+    if (!channel) {
+      this.core.logger.warn(`[NotificationManager] Channel '${channelName}' not found, skipping`);
+      return {
+        success: false,
+        channel: channelName,
+        error: new Error(`Channel '${channelName}' not registered`)
+      };
+    }
+    const retry = this.getRetryConfig(notification, retryConfig);
+    try {
+      if (retry) {
+        await withRetry(
+          () => this.executeChannelSend(channel, notification, notifiable, channelName),
+          {
+            ...retry,
+            shouldRetry: retry.retryableErrors || isRetryableError,
+            onRetry: (error, attempt, delay) => {
+              this.core.logger.warn(
+                `[NotificationManager] Channel '${channelName}' failed, retrying (${attempt}/${retry.maxAttempts}) in ${delay}ms`,
+                error
+              );
+              this.core.hooks.emit("notification:channel:retry", {
+                notification,
+                notifiable,
+                channel: channelName,
+                error,
+                attempt,
+                nextDelay: delay
+              });
+            }
+          }
         );
+      } else {
+        await this.executeChannelSend(channel, notification, notifiable, channelName);
+      }
+      const duration = Date.now() - startTime;
+      if (this.metrics) {
+        this.metrics.record({
+          notification: notification.constructor.name,
+          channel: channelName,
+          success: true,
+          duration,
+          timestamp: /* @__PURE__ */ new Date()
+        });
+      }
+      return {
+        success: true,
+        channel: channelName,
+        duration
+      };
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      const err = error instanceof Error ? error : new Error(String(error));
+      await this.core.hooks.emit("notification:channel:failed", {
+        notification,
+        notifiable,
+        channel: channelName,
+        error: err,
+        duration
+      });
+      this.core.logger.error(
+        `[NotificationManager] Failed to send notification via '${channelName}':`,
+        error
+      );
+      if (this.metrics) {
+        this.metrics.record({
+          notification: notification.constructor.name,
+          channel: channelName,
+          success: false,
+          duration,
+          timestamp: /* @__PURE__ */ new Date(),
+          error: err.message
+        });
+      }
+      return {
+        success: false,
+        channel: channelName,
+        error: err,
+        duration: Date.now() - startTime
+      };
+    }
+  }
+  async executeChannelSend(channel, notification, notifiable, channelName) {
+    await this.core.hooks.emit("notification:channel:sending", {
+      notification,
+      notifiable,
+      channel: channelName
+    });
+    await channel.send(notification, notifiable);
+    const duration = 0;
+    await this.core.hooks.emit("notification:channel:sent", {
+      notification,
+      notifiable,
+      channel: channelName,
+      duration
+    });
+  }
+  getRetryConfig(notification, options) {
+    const notificationRetry = notification.retry;
+    if (options === false || notificationRetry === void 0) {
+      if (typeof options === "object") {
+        return {
+          maxAttempts: 3,
+          baseDelay: 1e3,
+          backoff: "exponential",
+          maxDelay: 3e4,
+          ...options
+        };
       }
+      return void 0;
+    }
+    if (options || notificationRetry) {
+      const retryOptions = typeof options === "object" ? options : {};
+      return {
+        maxAttempts: 3,
+        baseDelay: 1e3,
+        backoff: "exponential",
+        maxDelay: 3e4,
+        ...notificationRetry,
+        ...retryOptions
+      };
     }
+    return void 0;
   }
   /**
    * Serialize notification (for queuing).
@@ -329,13 +820,7 @@ var NotificationManager = class {
    * @returns A plain object representation of the notification.
    */
   serializeNotification(notification) {
-    const data = {};
-    for (const [key, value] of Object.entries(notification)) {
-      if (!key.startsWith("_") && typeof value !== "function") {
-        data[key] = value;
-      }
-    }
-    return data;
+    return deepSerialize(notification);
   }
 };
 
@@ -343,6 +828,7 @@ var NotificationManager = class {
 var OrbitFlare = class _OrbitFlare {
   options;
   constructor(options = {}) {
+    this.validateOptions(options);
     this.options = {
       enableMail: true,
       enableDatabase: true,
@@ -361,6 +847,41 @@ var OrbitFlare = class _OrbitFlare {
   static configure(options = {}) {
     return new _OrbitFlare(options);
   }
+  validateOptions(options) {
+    if (options.enableSlack) {
+      const slack = options.channels?.slack;
+      if (!slack?.webhookUrl) {
+        throw new Error(
+          "[OrbitFlare] Slack channel enabled but webhookUrl not provided. Configure channels.slack.webhookUrl or set enableSlack to false."
+        );
+      }
+      if (!this.isValidUrl(slack.webhookUrl)) {
+        throw new Error(`[OrbitFlare] Invalid Slack webhook URL: ${slack.webhookUrl}`);
+      }
+    }
+    if (options.enableSms) {
+      const sms = options.channels?.sms;
+      if (!sms?.provider) {
+        throw new Error(
+          "[OrbitFlare] SMS channel enabled but provider not specified. Configure channels.sms.provider or set enableSms to false."
+        );
+      }
+      const supportedProviders = ["twilio", "aws-sns"];
+      if (!supportedProviders.includes(sms.provider)) {
+        throw new Error(
+          `[OrbitFlare] Unsupported SMS provider: ${sms.provider}. Supported providers: ${supportedProviders.join(", ")}`
+        );
+      }
+    }
+  }
+  isValidUrl(url) {
+    try {
+      new URL(url);
+      return true;
+    } catch {
+      return false;
+    }
+  }
   /**
    * Install OrbitFlare into PlanetCore.
    *
@@ -369,55 +890,133 @@ var OrbitFlare = class _OrbitFlare {
   async install(core) {
     const manager = new NotificationManager(core);
     if (this.options.enableMail) {
-      const mail = core.container.make("mail");
-      if (mail) {
-        manager.channel("mail", new MailChannel(mail));
-      } else {
-        core.logger.warn("[OrbitFlare] Mail service not found, mail channel disabled");
-      }
+      this.setupMailChannel(core, manager);
     }
     if (this.options.enableDatabase) {
-      const db = core.container.make("db");
-      if (db) {
-        manager.channel("database", new DatabaseChannel(db));
-      } else {
-        core.logger.warn("[OrbitFlare] Database service not found, database channel disabled");
-      }
+      this.setupDatabaseChannel(core, manager);
     }
     if (this.options.enableBroadcast) {
-      const broadcast = core.container.make("broadcast");
-      if (broadcast) {
-        manager.channel("broadcast", new BroadcastChannel(broadcast));
-      } else {
-        core.logger.warn("[OrbitFlare] Broadcast service not found, broadcast channel disabled");
-      }
+      this.setupBroadcastChannel(core, manager);
     }
     if (this.options.enableSlack) {
-      const slack = this.options.channels?.slack;
-      if (slack) {
-        manager.channel("slack", new SlackChannel(slack));
-      } else {
-        core.logger.warn("[OrbitFlare] Slack configuration not found, slack channel disabled");
-      }
+      this.setupSlackChannel(core, manager);
+    }
+    if (this.options.enableSms) {
+      this.setupSmsChannel(core, manager);
+    }
+    core.container.instance("notifications", manager);
+    this.setupQueueIntegration(core, manager);
+    core.logger.info("[OrbitFlare] Installed");
+  }
+  setupMailChannel(core, manager) {
+    const mail = core.container.make("mail");
+    if (mail && this.isMailService(mail)) {
+      manager.channel("mail", new MailChannel(mail));
+    } else {
+      core.logger.warn("[OrbitFlare] Mail service not found or invalid, mail channel disabled");
+    }
+  }
+  setupDatabaseChannel(core, manager) {
+    const db = core.container.make("db");
+    if (db && this.isDatabaseService(db)) {
+      manager.channel("database", new DatabaseChannel(db));
+    } else {
+      core.logger.warn(
+        "[OrbitFlare] Database service not found or invalid, database channel disabled"
+      );
+    }
+  }
+  setupBroadcastChannel(core, manager) {
+    const broadcast = core.container.make("broadcast");
+    if (broadcast && this.isBroadcastService(broadcast)) {
+      manager.channel("broadcast", new BroadcastChannel(broadcast));
+    } else {
+      core.logger.warn(
+        "[OrbitFlare] Broadcast service not found or invalid, broadcast channel disabled"
+      );
+    }
+  }
+  setupSlackChannel(core, manager) {
+    const slack = this.options.channels?.slack;
+    if (slack) {
+      manager.channel("slack", new SlackChannel(slack));
     }
     if (this.options.enableSms) {
       const sms = this.options.channels?.sms;
       if (sms) {
         manager.channel("sms", new SmsChannel(sms));
-      } else {
-        core.logger.warn("[OrbitFlare] SMS configuration not found, sms channel disabled");
       }
     }
-    core.container.instance("notifications", manager);
+  }
+  setupSmsChannel(core, manager) {
+    const sms = this.options.channels?.sms;
+    if (sms) {
+      manager.channel("sms", new SmsChannel(sms));
+    } else {
+      core.logger.warn("[OrbitFlare] SMS configuration not found, sms channel disabled");
+    }
+  }
+  setupQueueIntegration(core, manager) {
     const queue = core.container.make("queue");
-    if (queue) {
+    if (queue && this.isQueueService(queue)) {
       manager.setQueueManager({
         push: async (job, queueName, connection, delay) => {
           await queue.push(job, queueName, connection, delay);
         }
       });
     }
-    core.logger.info("[OrbitFlare] Installed");
+  }
+  isMailService(service) {
+    return typeof service === "object" && service !== null && "send" in service && typeof service.send === "function";
+  }
+  isDatabaseService(service) {
+    return typeof service === "object" && service !== null && "insertNotification" in service && typeof service.insertNotification === "function";
+  }
+  isBroadcastService(service) {
+    return typeof service === "object" && service !== null && "broadcast" in service && typeof service.broadcast === "function";
+  }
+  isQueueService(service) {
+    return typeof service === "object" && service !== null && "push" in service && typeof service.push === "function";
+  }
+};
+
+// src/templates/NotificationTemplate.ts
+var TemplatedNotification = class extends Notification {
+  data = {};
+  with(data) {
+    this.data = { ...this.data, ...data };
+    return this;
+  }
+  // Auto-implement toMail
+  toMail(notifiable) {
+    const template = this.mailTemplate();
+    return {
+      subject: this.interpolate(template.subject),
+      view: template.view,
+      data: { ...template.data, ...this.data },
+      to: this.getRecipientEmail(notifiable)
+    };
+  }
+  // Auto-implement toSlack
+  toSlack(_notifiable) {
+    if (!this.slackTemplate) {
+      throw new Error("slackTemplate not defined");
+    }
+    const template = this.slackTemplate();
+    return {
+      text: this.interpolate(template.text),
+      channel: template.channel,
+      attachments: template.attachments
+    };
+  }
+  interpolate(text) {
+    return text.replace(/\{\{(\w+)\}\}/g, (_, key) => String(this.data[key] ?? `{{${key}}}`));
+  }
+  getRecipientEmail(notifiable) {
+    if ("email" in notifiable && typeof notifiable.email === "string") {
+      return notifiable.email;
+    }
+    throw new Error("Notifiable does not have an email property");
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -427,7 +1026,10 @@ var OrbitFlare = class _OrbitFlare {
   MailChannel,
   Notification,
   NotificationManager,
+  NotificationMetricsCollector,
   OrbitFlare,
   SlackChannel,
-  SmsChannel
+  SmsChannel,
+  TemplatedNotification,
+  toPrometheusFormat
 });