Notification System

                    +-------------------+
   Event Source --> | Notification      | --> Channel Router --> Email Provider
   (App events,    | Service           |                    --> SMS Provider
    Webhooks,      | (Priority,        |                    --> Push Provider
    Schedules)     |  Dedup, Batch)    |                    --> Slack/Webhook
                    +-------------------+                    --> In-App Center
                           |
                    +------+------+
                    |             |
              User Prefs    Template Engine
              (Channel,     (Render per
               Quiet hrs,   channel with
               Frequency)   user locale)

// services/channels/email.ts
import { SES } from '@aws-sdk/client-ses';

interface EmailNotification {
    to: string;
    subject: string;
    htmlBody: string;
    textBody: string;
    replyTo?: string;
    tags?: Record<string, string>;
}

class EmailChannel {
    private ses: SES;
# ... (condensed) ...
        });

        return { messageId: result.MessageId! };
    }
}

// services/channels/sms.ts
import twilio from 'twilio';

class SMSChannel {
    private client: twilio.Twilio;

    constructor() {
        this.client = twilio(ENV_CONFIG_VALUE, ENV_CONFIG_VALUE);
    }

    async send(to: string, message: string): Promise<{ messageId: string }> {
        // SMS messages must be concise (160 chars for single segment)
        const truncated = message.length > 160
            ? message.substring(0, 157) + '...'
            # ... (condensed) ...
        });

        return { messageId: result.sid };
    }
}

// services/channels/push.ts
import * as admin from 'firebase-admin';

class PushChannel {
    private messaging: admin.messaging.Messaging;

    constructor() {
        admin.initializeApp({ credential: admin.credential.applicationDefault() });
        this.messaging = admin.messaging();
    }

    async send(deviceToken: string, notification: {
        title: string;
        body: string;
        # ... (condensed) ...
            notification,
        });
        return { messageId: result };
    }
}

// services/channels/webhook.ts
class WebhookChannel {
    async send(url: string, payload: any, options: {
        secret?: string;
        timeout?: number;
        retries?: number;
    } = {}): Promise<{ statusCode: number; responseTime: number }> {
        const body = JSON.stringify(payload);
        const headers: Record<string, string> = {
            'Content-Type': 'application/json',
            'User-Agent': 'MyApp-Webhook/1.0',
        };

        // Sign payload with HMAC for verification
        # ... (condensed) ...
            statusCode: response.status,
            responseTime: Date.now() - start,
        };
    }
}

// services/templates/engine.ts
import Handlebars from 'handlebars';

interface NotificationTemplate {
    id: string;
    channels: {
        email?: { subject: string; html: string; text: string };
        sms?: { body: string };
        push?: { title: string; body: string };
        slack?: { blocks: any[] };
    };
}

class TemplateEngine {
    # ... (condensed) ...
            title: 'Order Confirmed',
            body: 'Your order #{{orderId}} (${{total}}) is confirmed!',
        },
    },
});

// models/notificationPreferences.ts
interface NotificationPreferences {
    userId: string;
    channels: {
        email: boolean;
        sms: boolean;
        push: boolean;
        inApp: boolean;
    };
    categories: {
        [category: string]: {
            enabled: boolean;
            channels?: string[];  // Supersede default channels
            frequency?: 'immediate' | 'hourly_digest' | 'daily_digest';
        # ... (condensed) ...
        'social': { enabled: true, frequency: 'immediate' },
    },
    quietHours: { enabled: false, start: '22:00', end: '08:00', timezone: 'America/New_York' },
    unsubscribedAll: false,
};

class NotificationRouter {
    async route(notification: Notification, userId: string): Promise<string[]> {
        const prefs = await this.getPreferences(userId);

        // Global unsubscribe check (except mandatory categories)
        if (prefs.unsubscribedAll && !notification.mandatory) {
            return [];
        }

        // Category check
        const categoryPref = prefs.categories[notification.category];
        if (categoryPref && !categoryPref.enabled && !notification.mandatory) {
            return [];
        }
# ... (condensed) ...
            // Crosses midnight (e.g., 22:00 - 08:00)
            return now >= start || now < end;
        }
    }
}

// models/deliveryLog.ts
interface DeliveryLog {
    id: string;
    notificationId: string;
    userId: string;
    channel: string;
    status: 'pending' | 'sent' | 'delivered' | 'failed' | 'bounced' | 'clicked' | 'read';
    providerMessageId?: string;
    error?: string;
    attempts: number;
    sentAt?: Date;
    deliveredAt?: Date;
    readAt?: Date;
    metadata?: Record<string, any>;
# ... (condensed) ...
            error,
            attempts: log.attempts + 1,
        });
    }
}

class NotificationRetryHandler {
    private readonly maxRetries = 3;
    private readonly retryDelays = [60, 300, 900]; // 1min, 5min, 15min

    async handleFailure(delivery: DeliveryLog): Promise<void> {
        if (delivery.attempts >= this.maxRetries) {
            await this.markPermanentFailure(delivery);
            return;
        }

        const delay = this.retryDelays[delivery.attempts] || 900;

        // Determine if error is retryable
        if (this.isRetryable(delivery.error)) {
            # ... (condensed) ...
        if (fallback) {
            await this.resendViaChannel(delivery.notificationId, delivery.userId, fallback);
        }
    }
}

class DigestService {
    /**
     * Instead of sending 50 individual notifications,
     * batch them into a single digest email.
     */
    async processDigest(userId: string, frequency: 'hourly' | 'daily'): Promise<void> {
        const cutoff = frequency === 'hourly'
            ? new Date(Date.now() - 3600000)
            : new Date(Date.now() - 86400000);

        const pending = await db.notifications.findPending(userId, cutoff);

        if (pending.length === 0) return;

        # ... (condensed) ...
            (groups[n.category] = groups[n.category] || []).push(n);
            return groups;
        }, {} as Record<string, Notification[]>);
    }
}

class NotificationRateLimiter {
    // Limits per channel per user
    private limits: Record<string, { max: number; windowMs: number }> = {
        email: { max: 10, windowMs: 3600000 },     // 10 per hour
        sms: { max: 5, windowMs: 3600000 },         // 5 per hour
        push: { max: 20, windowMs: 3600000 },        // 20 per hour
        slack: { max: 30, windowMs: 3600000 },        // 30 per hour
    };

    async isAllowed(userId: string, channel: string): Promise<boolean> {
        const limit = this.limits[channel];
        if (!limit) return true;

        const key = `notif_rate:${userId}:${channel}`;
        # ... (condensed) ...
        }

        return count <= limit.max;
    }
}

enum NotificationPriority {
    LOW = 'low',           // In-app only, can be batched
    NORMAL = 'normal',     // Default channels, respects quiet hours
    HIGH = 'high',         // All enabled channels, respects quiet hours
    URGENT = 'urgent',     // All channels, ignores quiet hours, no batching
    CRITICAL = 'critical', // All channels + SMS, ignores all preferences
}

function getPriorityBehavior(priority: NotificationPriority) {
    return {
        low:      { respectQuietHours: true,  batchable: true,  fallbackChannel: false },
        normal:   { respectQuietHours: true,  batchable: true,  fallbackChannel: false },
        high:     { respectQuietHours: true,  batchable: false, fallbackChannel: true  },
        urgent:   { respectQuietHours: false, batchable: false, fallbackChannel: true  },
        critical: { respectQuietHours: false, batchable: false, fallbackChannel: true  },
    }[priority];
}

// GET /api/notifications?page=1&per_page=20&unread_only=false
interface NotificationCenterResponse {
    items: NotificationItem[];
    total: number;
    unread_count: number;
    page: number;
}

interface NotificationItem {
    id: string;
    title: string;
    body: string;
    category: string;
    priority: string;
    # ... (condensed) ...
}

// PATCH /api/notifications/:id/read
// POST /api/notifications/mark-all-read
// DELETE /api/notifications/:id

// WebSocket or Server-Sent Events for real-time notification delivery
// Server-Sent Events (simpler, one-directional)
app.get('/api/notifications/stream', (req, res) => {
    res.writeHead(200, {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
        'Connection': 'keep-alive',
    });

    const userId = req.user.id;

    const handler = (notification: NotificationItem) => {
        res.write(`data: ${JSON.stringify(notification)}\n\n`);
    };

    notificationBus.subscribe(userId, handler);

    req.on('close', () => {
        notificationBus.unsubscribe(userId, handler);
    });
});