@buenojs/bueno 0.8.10 → 0.8.11

package/dist/notification/service.js

@@ -0,0 +1,279 @@
+/**
+ * Notification Service
+ *
+ * Core notification service with registry-based channel management.
+ * Supports dynamic channel registration and multi-channel notification sending.
+ */
+import { isTemplateRef } from "./types";
+// ============= Notification Service =============
+export class NotificationService {
+    channels = new Map();
+    config;
+    metrics = new Map();
+    constructor(config = {}) {
+        this.config = config;
+    }
+    /**
+     * Register a channel service
+     * @param service Channel service to register
+     * @throws Error if channel is already registered
+     */
+    registerChannel(service) {
+        if (this.channels.has(service.name)) {
+            throw new Error(`Channel already registered: ${service.name}`);
+        }
+        this.channels.set(service.name, service);
+        // Initialize metrics
+        if (this.config.enableMetrics) {
+            this.metrics.set(service.name, {
+                sent: 0,
+                failed: 0,
+                successRate: 0,
+                avgSendTime: 0,
+                totalSendTime: 0,
+                updatedAt: new Date(),
+            });
+        }
+    }
+    /**
+     * Unregister a channel service
+     * @param channelName Name of the channel to unregister
+     */
+    unregisterChannel(channelName) {
+        this.channels.delete(channelName);
+        this.metrics.delete(channelName);
+    }
+    /**
+     * Get a registered channel service
+     * @param channelName Name of the channel
+     * @returns Channel service or null if not found
+     */
+    getChannel(channelName) {
+        return this.channels.get(channelName) || null;
+    }
+    /**
+     * Get all registered channel names
+     */
+    getChannels() {
+        return Array.from(this.channels.keys());
+    }
+    /**
+     * Check if a channel is registered
+     */
+    hasChannel(channelName) {
+        return this.channels.has(channelName);
+    }
+    /**
+     * Send a notification via specified channel
+     * @param message Notification message
+     * @returns Message ID or undefined
+     * @throws Error if channel not found or message invalid
+     */
+    async send(message) {
+        const startTime = Date.now();
+        try {
+            const service = this.channels.get(message.channel);
+            if (!service) {
+                throw new Error(`Channel not registered: ${message.channel}`);
+            }
+            // Resolve template references
+            const resolvedMessage = await this._resolveTemplates(message);
+            // Validate message
+            service.validate(resolvedMessage);
+            // Send message
+            const messageId = await service.send(resolvedMessage);
+            // Update metrics
+            if (this.config.enableMetrics) {
+                this._updateMetrics(message.channel, true, Date.now() - startTime);
+            }
+            return messageId;
+        }
+        catch (error) {
+            // Update metrics
+            if (this.config.enableMetrics) {
+                this._updateMetrics(message.channel, false, Date.now() - startTime);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Send multiple notifications (potentially different channels)
+     * @param messages Array of notification messages
+     * @returns Array of message IDs
+     */
+    async sendBatch(messages) {
+        const results = [];
+        for (const message of messages) {
+            try {
+                const messageId = await this.send(message);
+                results.push(messageId);
+            }
+            catch (error) {
+                results.push(undefined);
+            }
+        }
+        return results;
+    }
+    /**
+     * Send a notification from a Notifiable
+     * @param notifiable Notifiable instance
+     * @param channel Optional specific channel (otherwise uses buildAll or default)
+     * @returns Message ID(s)
+     */
+    async sendNotifiable(notifiable, channel) {
+        if (channel) {
+            // Send to specific channel
+            const message = await notifiable.build(channel);
+            return this.send(message);
+        }
+        // Try buildAll for multi-channel
+        if (notifiable.buildAll) {
+            const messages = await notifiable.buildAll();
+            const results = await this.sendBatch(Object.values(messages).filter((m) => m !== undefined));
+            return results[0]; // Return first message ID
+        }
+        // Fall back to build
+        const message = await notifiable.build();
+        return this.send(message);
+    }
+    /**
+     * Queue a notification for async sending (requires job queue integration)
+     * @param message Notification message
+     * @returns Job ID or undefined
+     */
+    async queue(message) {
+        // This will integrate with JobQueue in Phase 3
+        // For now, placeholder
+        return undefined;
+    }
+    /**
+     * Get health status for a channel
+     * @param channelName Name of the channel
+     */
+    async getChannelHealth(channelName) {
+        const service = this.channels.get(channelName);
+        if (!service)
+            return null;
+        return (service.getHealth?.() || {
+            status: "healthy",
+            message: "OK",
+            checkedAt: new Date(),
+        });
+    }
+    /**
+     * Get health status for all channels
+     */
+    async getHealthStatus() {
+        const health = {};
+        for (const [name] of this.channels) {
+            const channelHealth = await this.getChannelHealth(name);
+            if (channelHealth) {
+                health[name] = channelHealth;
+            }
+        }
+        return health;
+    }
+    /**
+     * Get metrics for a specific channel
+     * @param channelName Name of the channel
+     */
+    getChannelMetrics(channelName) {
+        return this.metrics.get(channelName) || null;
+    }
+    /**
+     * Get metrics for all channels
+     */
+    getAllMetrics() {
+        const allMetrics = {};
+        for (const [name, metrics] of this.metrics) {
+            allMetrics[name] = metrics;
+        }
+        return allMetrics;
+    }
+    /**
+     * Resolve TemplateRef objects in message fields to rendered strings
+     */
+    async _resolveTemplates(message) {
+        const engine = this.config.templateEngine;
+        if (!engine) {
+            // If no engine, check that no TemplateRef fields exist
+            this._assertNoTemplateRefs(message);
+            return message;
+        }
+        const channel = message.channel;
+        const msg = { ...message };
+        const resolveField = async (value, defaultFormat) => {
+            if (!isTemplateRef(value))
+                return value;
+            const fmt = value.outputFormat ?? defaultFormat;
+            const variant = value.variant ?? engine.getVariantForChannel(channel);
+            return engine.render(value.templateId, value.data, {
+                variant,
+                outputFormat: fmt,
+            });
+        };
+        // Email: resolve html (→ HTML) and text (→ text)
+        if (channel === "email") {
+            if (isTemplateRef(msg.html)) {
+                msg.html = await resolveField(msg.html, "html");
+            }
+            if (isTemplateRef(msg.text)) {
+                msg.text = await resolveField(msg.text, "text");
+            }
+        }
+        // SMS: resolve message (→ text)
+        else if (channel === "sms") {
+            if (isTemplateRef(msg.message)) {
+                msg.message = await resolveField(msg.message, "text");
+            }
+        }
+        // Push: resolve title and body (→ text)
+        else if (channel === "push") {
+            if (isTemplateRef(msg.title)) {
+                msg.title = await resolveField(msg.title, "text");
+            }
+            if (isTemplateRef(msg.body)) {
+                msg.body = await resolveField(msg.body, "text");
+            }
+        }
+        return msg;
+    }
+    /**
+     * Assert that no TemplateRef fields exist in the message
+     * Throws if a TemplateRef is found but no templateEngine is configured
+     */
+    _assertNoTemplateRefs(message) {
+        for (const [key, value] of Object.entries(message)) {
+            if (isTemplateRef(value)) {
+                throw new Error(`TemplateRef found in field "${key}" but no templateEngine is configured in NotificationService`);
+            }
+        }
+    }
+    /**
+     * Update metrics for a channel
+     */
+    _updateMetrics(channelName, success, duration) {
+        const metrics = this.metrics.get(channelName);
+        if (!metrics)
+            return;
+        if (success) {
+            metrics.sent++;
+            metrics.totalSendTime += duration;
+        }
+        else {
+            metrics.failed++;
+        }
+        const total = metrics.sent + metrics.failed;
+        metrics.successRate = total > 0 ? metrics.sent / total : 0;
+        metrics.avgSendTime =
+            metrics.sent > 0 ? metrics.totalSendTime / metrics.sent : 0;
+        metrics.updatedAt = new Date();
+    }
+}
+/**
+ * Factory function to create notification service
+ */
+export function createNotificationService(config) {
+    return new NotificationService(config);
+}
+//# sourceMappingURL=service.js.map

package/dist/notification/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/notification/service.ts"],"names":[],"mappings":"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"}

package/dist/notification/types.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Notification System Type Definitions
+ *
+ * Flexible multi-channel notification system with support for email, SMS,
+ * WhatsApp, push notifications, and custom channels. Uses registry pattern
+ * for dynamic channel registration.
+ */
+/**
+ * Supported notification channels
+ */
+export type NotificationChannel = "email" | "sms" | "whatsapp" | "push" | string;
+/**
+ * Base notification message interface
+ * All notification types must extend this
+ */
+export interface NotificationMessage {
+    /** Channel identifier */
+    channel: NotificationChannel;
+    /** Recipient identifier (email, phone, device ID, etc) */
+    recipient: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Reference to a template file with rendering data.
+ * Used in message fields that support template rendering.
+ * The NotificationService will resolve this to a rendered string before sending.
+ */
+export interface TemplateRef {
+    /** Template identifier (path without extension, e.g. "emails/welcome") */
+    templateId: string;
+    /** Data to pass to the template renderer */
+    data: Record<string, unknown>;
+    /** Optional variant override (e.g. "email", "sms"). Auto-detected from channel if omitted. */
+    variant?: string;
+    /** Output format: "html" or "text". Defaults based on field context. */
+    outputFormat?: "html" | "text";
+}
+/**
+ * Type guard for TemplateRef
+ */
+export declare function isTemplateRef(value: unknown): value is TemplateRef;
+export interface EmailRecipient {
+    name?: string;
+    email: string;
+}
+export type EmailRecipients = string | EmailRecipient | (string | EmailRecipient)[];
+export interface EmailAttachment {
+    filename: string;
+    content: string | Buffer;
+    contentType?: string;
+    encoding?: string;
+    contentDisposition?: "attachment" | "inline";
+    cid?: string;
+}
+export interface EmailMessage extends NotificationMessage {
+    channel: "email";
+    recipient: string;
+    subject: string;
+    html?: string | TemplateRef;
+    text?: string | TemplateRef;
+    cc?: EmailRecipients;
+    bcc?: EmailRecipients;
+    replyTo?: string;
+    from?: string;
+    attachments?: EmailAttachment[];
+    headers?: Record<string, string>;
+    messageId?: string;
+    references?: string[];
+    inReplyTo?: string;
+    tags?: string[];
+    priority?: "high" | "normal" | "low";
+    scheduledAt?: Date;
+}
+export interface SMSMessage extends NotificationMessage {
+    channel: "sms";
+    recipient: string;
+    message: string | TemplateRef;
+    senderId?: string;
+    scheduledAt?: Date;
+}
+export interface WhatsAppMessage extends NotificationMessage {
+    channel: "whatsapp";
+    recipient: string;
+    templateId: string;
+    parameters?: Record<string, string>;
+    mediaUrl?: string;
+}
+export interface PushNotificationMessage extends NotificationMessage {
+    channel: "push";
+    recipient: string;
+    title: string | TemplateRef;
+    body: string | TemplateRef;
+    actionUrl?: string;
+    imageUrl?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Union of all built-in notification types
+ */
+export type BuiltInNotification = EmailMessage | SMSMessage | WhatsAppMessage | PushNotificationMessage;
+/**
+ * Interface for composable notification messages
+ * Implement this interface to create reusable notification templates
+ */
+export interface Notifiable {
+    /**
+     * Build notification message(s)
+     * Can return single message or array of messages for multi-channel
+     * @returns NotificationMessage or Promise<NotificationMessage>
+     */
+    build(channel?: NotificationChannel): NotificationMessage | Promise<NotificationMessage>;
+    /**
+     * Optional: Build multiple channel notifications at once
+     */
+    buildAll?(): Record<NotificationChannel, NotificationMessage | Promise<NotificationMessage>>;
+}
+/**
+ * Health status for channel services
+ */
+export interface ChannelHealth {
+    status: "healthy" | "degraded" | "unhealthy";
+    message: string;
+    checkedAt: Date;
+    error?: string;
+}
+/**
+ * Base interface for all channel services
+ */
+export interface ChannelService<T extends NotificationMessage = NotificationMessage> {
+    /** Channel name/identifier */
+    readonly name: NotificationChannel;
+    /** Configuration schema validator (optional) */
+    readonly configSchema?: StandardSchema;
+    /**
+     * Validate message structure at runtime
+     * Should throw if message is invalid
+     */
+    validate(message: unknown): asserts message is T;
+    /**
+     * Send a notification message
+     * @returns Message ID or undefined if not trackable
+     */
+    send(message: T): Promise<string | undefined>;
+    /**
+     * Get channel health status
+     */
+    getHealth?(): Promise<ChannelHealth>;
+    /**
+     * Get channel metrics (optional)
+     */
+    getMetrics?(): Promise<ChannelMetrics>;
+}
+export interface BaseChannelConfig {
+    /** Enable this channel */
+    enabled?: boolean;
+    /** Dry-run mode (log instead of sending) */
+    dryRun?: boolean;
+    /** Enable metrics collection */
+    enableMetrics?: boolean;
+}
+export interface EmailChannelConfig extends BaseChannelConfig {
+    driver: "smtp" | "sendgrid" | "brevo" | "resend";
+    from: string;
+    fromName?: string;
+    smtp?: {
+        host: string;
+        port: number;
+        secure?: boolean;
+        username?: string;
+        password?: string;
+    };
+    apiKey?: string;
+}
+export interface SMSChannelConfig extends BaseChannelConfig {
+    driver: "twilio" | "aws-sns" | "custom";
+    accountSid?: string;
+    authToken?: string;
+    fromNumber?: string;
+    apiKey?: string;
+}
+export interface WhatsAppChannelConfig extends BaseChannelConfig {
+    driver: "twilio" | "custom";
+    accountSid?: string;
+    authToken?: string;
+    businessPhoneNumber?: string;
+    apiKey?: string;
+}
+export interface PushChannelConfig extends BaseChannelConfig {
+    driver: "firebase" | "apns" | "custom";
+    serverKey?: string;
+    certificatePath?: string;
+    apiKey?: string;
+}
+export type ChannelConfig = EmailChannelConfig | SMSChannelConfig | WhatsAppChannelConfig | PushChannelConfig | Record<string, unknown>;
+export interface NotificationServiceConfig {
+    /** Channels configuration */
+    channels?: Record<NotificationChannel, ChannelConfig>;
+    /** Default channel for sending */
+    defaultChannel?: NotificationChannel;
+    /** Queue system for async sending */
+    queue?: boolean;
+    /** Enable metrics collection */
+    enableMetrics?: boolean;
+    /** Optional template engine for rendering TemplateRef fields */
+    templateEngine?: import("../templates/engine").TemplateEngine;
+}
+export interface ChannelMetrics {
+    /** Total messages sent */
+    sent: number;
+    /** Total messages failed */
+    failed: number;
+    /** Successful send rate (0-1) */
+    successRate: number;
+    /** Average send time in ms */
+    avgSendTime: number;
+    /** Total time spent sending */
+    totalSendTime: number;
+    /** Last updated timestamp */
+    updatedAt: Date;
+}
+export type NotificationEventType = "notification.sent" | "notification.failed" | "notification.queued" | "notification.bounced" | "notification.delivered";
+export interface NotificationEvent {
+    type: NotificationEventType;
+    channel: NotificationChannel;
+    messageId?: string;
+    recipient?: string;
+    timestamp: Date;
+    data?: Record<string, unknown>;
+}
+export interface NotificationValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export interface StandardSchema<T = unknown> {
+    "~standard": {
+        version: number;
+        types?: {
+            input: unknown;
+            output: T;
+        };
+        validate: (value: unknown) => Promise<{
+            issues?: Array<{
+                message: string;
+                path?: Array<PropertyKey | {
+                    key: PropertyKey;
+                }>;
+            }>;
+        }>;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/notification/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/notification/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC5B,OAAO,GACP,KAAK,GACL,UAAU,GACV,MAAM,GACN,MAAM,CAAC;AAEV;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,yBAAyB;IACzB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAID;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAID,MAAM,WAAW,cAAc;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,eAAe,GACxB,MAAM,GACN,cAAc,GACd,CAAC,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC;AAE/B,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,YAAY,GAAG,QAAQ,CAAC;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAa,SAAQ,mBAAmB;IACxD,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC5B,EAAE,CAAC,EAAE,eAAe,CAAC;IACrB,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACrC,WAAW,CAAC,EAAE,IAAI,CAAC;CACnB;AAID,MAAM,WAAW,UAAW,SAAQ,mBAAmB;IACtD,OAAO,EAAE,KAAK,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,IAAI,CAAC;CACnB;AAID,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;IAC3D,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC;IAC5B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAID;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC5B,YAAY,GACZ,UAAU,GACV,eAAe,GACf,uBAAuB,CAAC;AAI3B;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B;;;;OAIG;IACH,KAAK,CACJ,OAAO,CAAC,EAAE,mBAAmB,GAC3B,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEtD;;OAEG;IACH,QAAQ,CAAC,IAAI,MAAM,CAClB,mBAAmB,EACnB,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAClD,CAAC;CACF;AAID;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAC9B,CAAC,SAAS,mBAAmB,GAAG,mBAAmB;IAEnD,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAEnC,gDAAgD;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;IAEjD;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE9C;;OAEG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IAErC;;OAEG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;CACvC;AAID,MAAM,WAAW,iBAAiB;IACjC,0BAA0B;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gCAAgC;IAChC,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC5D,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IAC1D,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC/D,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC3D,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,aAAa,GACtB,kBAAkB,GAClB,gBAAgB,GAChB,qBAAqB,GACrB,iBAAiB,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAI3B,MAAM,WAAW,yBAAyB;IACzC,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,mBAAmB,EAAE,aAAa,CAAC,CAAC;IACtD,kCAAkC;IAClC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,qCAAqC;IACrC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gCAAgC;IAChC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,qBAAqB,EAAE,cAAc,CAAC;CAC9D;AAID,MAAM,WAAW,cAAc;IAC9B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,SAAS,EAAE,IAAI,CAAC;CAChB;AAID,MAAM,MAAM,qBAAqB,GAC9B,mBAAmB,GACnB,qBAAqB,GACrB,qBAAqB,GACrB,sBAAsB,GACtB,wBAAwB,CAAC;AAE5B,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAID,MAAM,WAAW,4BAA4B;IAC5C,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAID,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IAC1C,WAAW,EAAE;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE;YACP,KAAK,EAAE,OAAO,CAAC;YACf,MAAM,EAAE,CAAC,CAAC;SACV,CAAC;QACF,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;YACrC,MAAM,CAAC,EAAE,KAAK,CAAC;gBACd,OAAO,EAAE,MAAM,CAAC;gBAChB,IAAI,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG;oBAAE,GAAG,EAAE,WAAW,CAAA;iBAAE,CAAC,CAAC;aACjD,CAAC,CAAC;SACH,CAAC,CAAC;KACH,CAAC;CACF"}

package/dist/notification/types.js

@@ -0,0 +1,14 @@
+/**
+ * Notification System Type Definitions
+ *
+ * Flexible multi-channel notification system with support for email, SMS,
+ * WhatsApp, push notifications, and custom channels. Uses registry pattern
+ * for dynamic channel registration.
+ */
+/**
+ * Type guard for TemplateRef
+ */
+export function isTemplateRef(value) {
+    return typeof value === "object" && value !== null && "templateId" in value;
+}
+//# sourceMappingURL=types.js.map

package/dist/notification/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/notification/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6CH;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,YAAY,IAAI,KAAK,CAAC;AAC7E,CAAC"}

package/dist/observability/__tests__/observability.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=observability.test.d.ts.map

package/dist/observability/__tests__/observability.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.test.d.ts","sourceRoot":"","sources":["../../../src/observability/__tests__/observability.test.ts"],"names":[],"mappings":""}