@buenojs/bueno 0.8.3 → 0.8.5

package/src/notification/channels/sms.ts

@@ -0,0 +1,105 @@
+/**
+ * SMS Channel Service
+ *
+ * Sends notifications via SMS through various drivers
+ * (Twilio, AWS SNS, custom)
+ */
+
+import type { SMSChannelConfig, SMSMessage } from "../types";
+import { BaseChannelService } from "./base";
+
+// ============= SMS Channel Service =============
+
+export class SMSChannelService extends BaseChannelService<SMSMessage> {
+	readonly name = "sms";
+	private config: SMSChannelConfig;
+	private sentCount = 0;
+	private failureCount = 0;
+
+	constructor(config: SMSChannelConfig) {
+		super();
+		this.config = config;
+	}
+
+	/**
+	 * Validate SMS message structure
+	 */
+	validate(message: unknown): asserts message is SMSMessage {
+		if (typeof message !== "object" || message === null) {
+			throw new Error("Invalid SMS message: must be an object");
+		}
+
+		const msg = message as Record<string, unknown>;
+
+		if (msg.channel !== "sms") {
+			throw new Error('Invalid SMS message: channel must be "sms"');
+		}
+
+		if (typeof msg.recipient !== "string" || msg.recipient.length === 0) {
+			throw new Error(
+				"Invalid SMS message: recipient (phone number) is required",
+			);
+		}
+
+		if (typeof msg.message !== "string" || msg.message.length === 0) {
+			throw new Error("Invalid SMS message: message is required");
+		}
+
+		if (msg.message.length > 160) {
+			console.warn(
+				`SMS message exceeds 160 characters (${msg.message.length}), will be split`,
+			);
+		}
+	}
+
+	/**
+	 * Send SMS message
+	 */
+	async send(message: SMSMessage): Promise<string | undefined> {
+		try {
+			if (this.config.dryRun) {
+				console.log(`[SMSChannel] Would send SMS to: ${message.recipient}`);
+				console.log(`  Message: ${message.message.substring(0, 50)}...`);
+				this.sentCount++;
+				return this._generateMessageId();
+			}
+
+			// In a real implementation, delegate to appropriate driver
+			// For now, simulate sending
+			const messageId = this._generateMessageId();
+			console.log(
+				`[SMSChannel] SMS sent: ${messageId} to ${message.recipient}`,
+			);
+			this.sentCount++;
+
+			return messageId;
+		} catch (error) {
+			this.failureCount++;
+			throw new Error(
+				`Failed to send SMS: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
+	/**
+	 * Get SMS channel metrics
+	 */
+	getMetrics() {
+		const total = this.sentCount + this.failureCount;
+		return {
+			sent: this.sentCount,
+			failed: this.failureCount,
+			total,
+			successRate: total > 0 ? this.sentCount / total : 0,
+		};
+	}
+
+	/**
+	 * Generate a message ID
+	 */
+	private _generateMessageId(): string {
+		const timestamp = Date.now();
+		const random = Math.random().toString(36).substring(2, 15);
+		return `sms_${timestamp}_${random}`;
+	}
+}

package/src/notification/channels/whatsapp.ts

@@ -0,0 +1,104 @@
+/**
+ * WhatsApp Channel Service
+ *
+ * Sends notifications via WhatsApp through various drivers
+ * (Twilio, custom)
+ */
+
+import type { WhatsAppChannelConfig, WhatsAppMessage } from "../types";
+import { BaseChannelService } from "./base";
+
+// ============= WhatsApp Channel Service =============
+
+export class WhatsAppChannelService extends BaseChannelService<WhatsAppMessage> {
+	readonly name = "whatsapp";
+	private config: WhatsAppChannelConfig;
+	private sentCount = 0;
+	private failureCount = 0;
+
+	constructor(config: WhatsAppChannelConfig) {
+		super();
+		this.config = config;
+	}
+
+	/**
+	 * Validate WhatsApp message structure
+	 */
+	validate(message: unknown): asserts message is WhatsAppMessage {
+		if (typeof message !== "object" || message === null) {
+			throw new Error("Invalid WhatsApp message: must be an object");
+		}
+
+		const msg = message as Record<string, unknown>;
+
+		if (msg.channel !== "whatsapp") {
+			throw new Error('Invalid WhatsApp message: channel must be "whatsapp"');
+		}
+
+		if (typeof msg.recipient !== "string" || msg.recipient.length === 0) {
+			throw new Error(
+				"Invalid WhatsApp message: recipient (phone number) is required",
+			);
+		}
+
+		if (typeof msg.templateId !== "string" || msg.templateId.length === 0) {
+			throw new Error("Invalid WhatsApp message: templateId is required");
+		}
+	}
+
+	/**
+	 * Send WhatsApp message
+	 */
+	async send(message: WhatsAppMessage): Promise<string | undefined> {
+		try {
+			if (this.config.dryRun) {
+				console.log(
+					`[WhatsAppChannel] Would send WhatsApp to: ${message.recipient}`,
+				);
+				console.log(`  Template: ${message.templateId}`);
+				console.log(
+					`  Parameters: ${JSON.stringify(message.parameters || {})}`,
+				);
+				this.sentCount++;
+				return this._generateMessageId();
+			}
+
+			// In a real implementation, delegate to appropriate driver
+			// For now, simulate sending
+			const messageId = this._generateMessageId();
+			console.log(
+				`[WhatsAppChannel] WhatsApp sent: ${messageId} to ${message.recipient}`,
+			);
+			this.sentCount++;
+
+			return messageId;
+		} catch (error) {
+			this.failureCount++;
+			throw new Error(
+				`Failed to send WhatsApp: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
+	/**
+	 * Get WhatsApp channel metrics
+	 */
+	getMetrics() {
+		const total = this.sentCount + this.failureCount;
+		return {
+			sent: this.sentCount,
+			failed: this.failureCount,
+			total,
+			successRate: total > 0 ? this.sentCount / total : 0,
+		};
+	}
+
+	/**
+	 * Generate a message ID
+	 */
+	private _generateMessageId(): string {
+		const timestamp = Date.now();
+		const random = Math.random().toString(36).substring(2, 15);
+		return `wa_${timestamp}_${random}`;
+	}
+}

package/src/notification/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Notification Module
+ *
+ * Multi-channel notification system with support for email, SMS, WhatsApp,
+ * push notifications, and custom channels. Uses registry pattern for
+ * dynamic channel registration.
+ */
+
+// Export types
+export type {
+	NotificationChannel,
+	NotificationMessage,
+	EmailRecipient,
+	EmailRecipients,
+	EmailAttachment,
+	EmailMessage,
+	SMSMessage,
+	WhatsAppMessage,
+	PushNotificationMessage,
+	BuiltInNotification,
+	Notifiable,
+	ChannelHealth,
+	ChannelService,
+	BaseChannelConfig,
+	EmailChannelConfig,
+	SMSChannelConfig,
+	WhatsAppChannelConfig,
+	PushChannelConfig,
+	ChannelConfig,
+	NotificationServiceConfig,
+	ChannelMetrics,
+	NotificationEvent,
+	NotificationEventType,
+	NotificationValidationResult,
+	StandardSchema,
+} from "./types";
+
+// Export service
+export { NotificationService, createNotificationService } from "./service";
+
+// Export base channel
+export { BaseChannelService } from "./channels/base";
+
+// Export built-in channels
+export { EmailChannelService } from "./channels/email";
+export { SMSChannelService } from "./channels/sms";
+export { WhatsAppChannelService } from "./channels/whatsapp";
+export { PushNotificationChannelService } from "./channels/push";

package/src/notification/service.ts

@@ -0,0 +1,354 @@
+/**
+ * Notification Service
+ *
+ * Core notification service with registry-based channel management.
+ * Supports dynamic channel registration and multi-channel notification sending.
+ */
+
+import type {
+	ChannelHealth,
+	ChannelMetrics,
+	ChannelService,
+	Notifiable,
+	NotificationChannel,
+	NotificationMessage,
+	NotificationServiceConfig,
+	TemplateRef,
+} from "./types";
+import { isTemplateRef } from "./types";
+
+// ============= Notification Service =============
+
+export class NotificationService {
+	private channels: Map<NotificationChannel, ChannelService> = new Map();
+	private config: NotificationServiceConfig;
+	private metrics: Map<NotificationChannel, ChannelMetrics> = new Map();
+
+	constructor(config: NotificationServiceConfig = {}) {
+		this.config = config;
+	}
+
+	/**
+	 * Register a channel service
+	 * @param service Channel service to register
+	 * @throws Error if channel is already registered
+	 */
+	registerChannel<T extends NotificationMessage>(
+		service: ChannelService<T>,
+	): void {
+		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: NotificationChannel): void {
+		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: NotificationChannel): ChannelService | null {
+		return this.channels.get(channelName) || null;
+	}
+
+	/**
+	 * Get all registered channel names
+	 */
+	getChannels(): NotificationChannel[] {
+		return Array.from(this.channels.keys());
+	}
+
+	/**
+	 * Check if a channel is registered
+	 */
+	hasChannel(channelName: NotificationChannel): boolean {
+		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: NotificationMessage): Promise<string | undefined> {
+		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: NotificationMessage[],
+	): Promise<(string | undefined)[]> {
+		const results: (string | undefined)[] = [];
+
+		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: Notifiable,
+		channel?: NotificationChannel,
+	): Promise<string | undefined> {
+		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,
+				) as NotificationMessage[],
+			);
+			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: NotificationMessage): Promise<string | undefined> {
+		// 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: NotificationChannel,
+	): Promise<ChannelHealth | null> {
+		const service = this.channels.get(channelName);
+		if (!service) return null;
+
+		return (
+			service.getHealth?.() || {
+				status: "healthy" as const,
+				message: "OK",
+				checkedAt: new Date(),
+			}
+		);
+	}
+
+	/**
+	 * Get health status for all channels
+	 */
+	async getHealthStatus(): Promise<Record<NotificationChannel, ChannelHealth>> {
+		const health: Record<NotificationChannel, ChannelHealth> = {};
+
+		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: NotificationChannel): ChannelMetrics | null {
+		return this.metrics.get(channelName) || null;
+	}
+
+	/**
+	 * Get metrics for all channels
+	 */
+	getAllMetrics(): Record<NotificationChannel, ChannelMetrics> {
+		const allMetrics: Record<NotificationChannel, ChannelMetrics> = {};
+
+		for (const [name, metrics] of this.metrics) {
+			allMetrics[name] = metrics;
+		}
+
+		return allMetrics;
+	}
+
+	/**
+	 * Resolve TemplateRef objects in message fields to rendered strings
+	 */
+	private async _resolveTemplates(
+		message: NotificationMessage,
+	): Promise<NotificationMessage> {
+		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 } as Record<string, unknown>;
+
+		const resolveField = async (
+			value: unknown,
+			defaultFormat: "html" | "text",
+		): Promise<string> => {
+			if (!isTemplateRef(value)) return value as string;
+			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 as NotificationMessage;
+	}
+
+	/**
+	 * Assert that no TemplateRef fields exist in the message
+	 * Throws if a TemplateRef is found but no templateEngine is configured
+	 */
+	private _assertNoTemplateRefs(message: Record<string, unknown>): void {
+		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
+	 */
+	private _updateMetrics(
+		channelName: NotificationChannel,
+		success: boolean,
+		duration: number,
+	): void {
+		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?: NotificationServiceConfig,
+): NotificationService {
+	return new NotificationService(config);
+}