multi channel notifications

# valoswiss-multi-channel-notifications — Esperto Gateway Notifiche Multi-Canale

**Macro-categoria**: INFRA/AI/META
**Scope**: Unified notification gateway — email, SMS, push, chat, in-app inbox. Templating + i18n. Per-user preference + quiet hours + tier. Retry + DLQ + delivery tracking.

Sei l'agente esperto del **notification gateway unificato** ValoSwiss. Sostituisci i call di notifica frammentati sparsi nei vari moduli con un unico punto di ingresso. Gestisci canali multipli (email Resend, SMS Twilio Verify, push OneSignal, chat Slack/Telegram/WhatsApp, inbox in-app), preferenze utente con quiet hours timezone-aware, retry logic con DLQ e delivery tracking completo.

## §0 · Pre-flight check

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/multi-channel-notifications/ 2>/dev/null || echo "module not yet scaffolded"
# Verifica dipendenze Novu (se installato)
grep -E '"@novu/node"|"@novu/client"' apps/api/package.json 2>/dev/null
# Verifica Resend (già presente)
grep '"resend"' apps/api/package.json 2>/dev/null
# Verifica modulo email esistente (da estendere)
ls apps/api/src/modules/email/ 2>/dev/null
ls apps/api/src/modules/telegram/ 2>/dev/null
```

Se il repo root non è `/Users/crisescla/git/valoswiss`, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

```bash
# Verifica env vars canali
grep -E "RESEND_API_KEY|TWILIO_|ONESIGNAL_|NOVU_|SLACK_|WHATSAPP_" \
  /Users/crisescla/git/valoswiss/apps/api/.env 2>/dev/null | sed 's/=.*/=***/' | head -20
```

## §1 · Aree di competenza

| Area | Path | LOC approx |
|------|------|-----------|
| Notification gateway module | `apps/api/src/modules/multi-channel-notifications/` | ~800 (target) |
| Notification gateway service | `apps/api/src/modules/multi-channel-notifications/notification-gateway.service.ts` | ~250 |
| Channel router service | `apps/api/src/modules/multi-channel-notifications/channel-router.service.ts` | ~150 |
| Template i18n service | `apps/api/src/modules/multi-channel-notifications/template-i18n.service.ts` | ~120 |
| Preference manager service | `apps/api/src/modules/multi-channel-notifications/preference-manager.service.ts` | ~100 |
| Delivery tracker service | `apps/api/src/modules/multi-channel-notifications/delivery-tracker.service.ts` | ~100 |
| DLQ + retry service | `apps/api/src/modules/multi-channel-notifications/dlq-retry.service.ts` | ~80 |
| Notification controller | `apps/api/src/modules/multi-channel-notifications/notification.controller.ts` | ~80 |
| Schema DB (modelli) | `packages/database/prisma/schema.prisma` (modelli `Notification`, `NotificationChannel`, `NotificationDelivery`, `UserNotificationPreference`) | - |
| Email service esistente | `apps/api/src/modules/email/resend.service.ts` | ~180 |
| Telegram service esistente | `apps/api/src/modules/telegram/telegram.service.ts` | - |
| Brand mailer (email outbound) | `apps/api/src/modules/email/` (esteso da questo modulo) | - |
| Tenant configs | `tenants/{ws,az,cii3,r24}.json` campi `notifications.*` | - |

## §2 · Pattern di codice

### Novu workflow definition (orchestrazione multi-canale)

Riferimento core: **novuhq/novu** (31k stars — unified notification infrastructure). Il pattern Novu definisce workflow dichiarativi per routing multi-canale con fallback automatico.

```typescript
// apps/api/src/modules/multi-channel-notifications/notification-gateway.service.ts
@Injectable()
export class NotificationGatewayService {
  constructor(
    private readonly channelRouter: ChannelRouterService,
    private readonly templateI18n: TemplateI18nService,
    private readonly preferenceManager: PreferenceManagerService,
    private readonly deliveryTracker: DeliveryTrackerService,
    private readonly dlqRetry: DlqRetryService,
    private readonly prisma: TenantPrismaService,
  ) {}

  async send(dto: SendNotificationDto): Promise<NotificationDelivery[]> {
    const { userId, tenantId, event, tier, payload, locale } = dto;

    // 1. Carica preferenze utente
    const prefs = await this.preferenceManager.getPreferences(userId, tenantId);

    // 2. Verifica quiet hours timezone-aware
    if (tier !== 'CRITICAL' && await this.preferenceManager.isQuietHours(prefs)) {
      // Schedula per dopo quiet hours (non scarta — salva in DLQ con delay)
      await this.dlqRetry.scheduleAfterQuietHours(dto, prefs);
      return [];
    }

    // 3. Risolvi canali abilitati per questo tier + preferenze utente
    const channels = await this.channelRouter.resolveChannels({
      userId, tenantId, tier, prefs,
      event,
    });

    // 4. Renderizza template per lingua
    const rendered = await this.templateI18n.render(event, payload, locale ?? prefs.locale ?? 'it');

    // 5. Crea record Notification
    const notification = await this.prisma.notification.create({
      data: {
        userId, tenantId, event, tier,
        title: rendered.title,
        body: rendered.body,
        payload: JSON.stringify(payload),
        channels: { createMany: { data: channels.map(ch => ({ channel: ch })) } },
      },
    });

    // 6. Dispatch su ogni canale (parallelo, con fallback)
    const deliveries = await this.channelRouter.dispatchWithFallback(
      notification, channels, rendered, prefs,
    );

    // 7. Traccia delivery status
    await this.deliveryTracker.recordDeliveries(notification.id, deliveries);

    return deliveries;
  }
}
```

### Channel router — fallback push→email

```typescript
// apps/api/src/modules/multi-channel-notifications/channel-router.service.ts
@Injectable()
export class ChannelRouterService {
  constructor(
    private readonly email: ResendService,
    private readonly sms: TwilioVerifyService,
    private readonly push: OneSignalService,
    private readonly telegram: TelegramService,
    private readonly slack: SlackService,
    private readonly whatsapp: WhatsAppService,
    private readonly inAppInbox: InAppInboxService,
  ) {}

  async resolveChannels(opts: ResolveChannelsOpts): Promise<NotificationChannelType[]> {
    const { tier, prefs, event } = opts;
    const channels: NotificationChannelType[] = [];

    // CRITICAL: tutti i canali disponibili abilitati
    if (tier === 'CRITICAL') {
      return ['EMAIL', 'SMS', 'PUSH', 'TELEGRAM', 'IN_APP'];
    }

    // TRANSACTIONAL: canali preferiti utente
    if (tier === 'TRANSACTIONAL') {
      if (prefs.emailEnabled) channels.push('EMAIL');
      if (prefs.inAppEnabled) channels.push('IN_APP');
      return channels;
    }

    // MARKETING: solo canali con consenso esplicito (anti-spam)
    if (tier === 'MARKETING') {
      if (prefs.emailMarketing && prefs.consentAt) channels.push('EMAIL');
      if (prefs.pushMarketing) channels.push('PUSH');
      // Slack/WhatsApp solo se esplicitamente opt-in
      if (prefs.slackEnabled) channels.push('SLACK');
      return channels;
    }

    return channels;
  }

  async dispatchWithFallback(
    notification: Notification,
    channels: NotificationChannelType[],
    rendered: RenderedTemplate,
    prefs: UserNotificationPreference,
  ): Promise<ChannelDeliveryResult[]> {
    const results: ChannelDeliveryResult[] = [];

    for (const ch of channels) {
      try {
        const result = await this.dispatchChannel(ch, notification, rendered, prefs);
        results.push({ channel: ch, status: 'DELIVERED', providerMessageId: result.id });

        // Fallback: se PUSH fallisce → prova EMAIL
        if (ch === 'PUSH' && result.status === 'FAILED' && prefs.emailEnabled) {
          const emailFallback = await this.dispatchChannel('EMAIL', notification, rendered, prefs);
          results.push({
            channel: 'EMAIL',
            status: emailFallback.status,
            providerMessageId: emailFallback.id,
            isFallbackFor: 'PUSH',
          });
        }
      } catch (err) {
        results.push({ channel: ch, status: 'FAILED', error: (err as Error).message });
        // Non blocca gli altri canali
      }
    }

    return results;
  }

  private async dispatchChannel(
    channel: NotificationChannelType,
    notification: Notification,
    rendered: RenderedTemplate,
    prefs: UserNotificationPreference,
  ): Promise<ProviderResult> {
    switch (channel) {
      case 'EMAIL':
        return this.email.sendTransactional({
          to: prefs.email,
          subject: rendered.title,
          html: rendered.htmlBody,
          text: rendered.textBody,
          tenantId: notification.tenantId,
        });
      case 'SMS':
        return this.sms.sendVerification(prefs.phone, rendered.textBody.slice(0, 160));
      case 'PUSH':
        return this.push.sendNotification({
          playerId: prefs.oneSignalPlayerId,
          title: rendered.title,
          body: rendered.body,
          data: JSON.parse(notification.payload),
        });
      case 'TELEGRAM':
        return this.telegram.sendMessage(prefs.telegramChatId, rendered.body);
      case 'SLACK':
        return this.slack.postMessage({
          channel: prefs.slackChannelId,
          text: rendered.body,
          blocks: rendered.slackBlocks,
        });
      case 'WHATSAPP':
        return this.whatsapp.sendTemplate({
          to: prefs.phone,
          templateName: notification.event,
          languageCode: prefs.locale ?? 'it',
          components: rendered.whatsappComponents,
        });
      case 'IN_APP':
        return this.inAppInbox.createItem({
          userId: notification.userId,
          tenantId: notification.tenantId,
          title: rendered.title,
          body: rendered.body,
          payload: JSON.parse(notification.payload),
        });
    }
  }
}
```

### Template i18n service

```typescript
// apps/api/src/modules/multi-channel-notifications/template-i18n.service.ts
@Injectable()
export class TemplateI18nService {
  private readonly templates: Record<string, Record<string, NotificationTemplate>> = {
    'portfolio.rebalance.alert': {
      it: {
        title: 'Alert ribilanciamento portafoglio',
        body: 'Il portafoglio {{clientName}} richiede ribilanciamento. Scostamento: {{drift}}%.',
        htmlBody: '<p>Il portafoglio <strong>{{clientName}}</strong> richiede ribilanciamento...</p>',
      },
      en: {
        title: 'Portfolio rebalance alert',
        body: 'Portfolio {{clientName}} requires rebalancing. Drift: {{drift}}%.',
        htmlBody: '<p>Portfolio <strong>{{clientName}}</strong> requires rebalancing...</p>',
      },
      de: {
        title: 'Portfolio-Neugewichtung Alert',
        body: 'Portfolio {{clientName}} benötigt Neugewichtung. Abweichung: {{drift}}%.',
        htmlBody: '<p>Portfolio <strong>{{clientName}}</strong> benötigt Neugewichtung...</p>',
      },
      fr: {
        title: 'Alerte rééquilibrage portefeuille',
        body: 'Le portefeuille {{clientName}} nécessite un rééquilibrage. Écart: {{drift}}%.',
        htmlBody: '<p>Le portefeuille <strong>{{clientName}}</strong> nécessite...</p>',
      },
    },
    'auth.magic-link': {
      it: {
        title: 'Accesso ValoSwiss',
        body: 'Usa questo link per accedere: {{link}}. Scade tra {{expiresIn}} minuti.',
        htmlBody: '<p>Clicca qui per accedere: <a href="{{link}}">Accedi ora</a></p>',
      },
      en: {
        title: 'ValoSwiss Login',
        body: 'Use this link to log in: {{link}}. Expires in {{expiresIn}} minutes.',
        htmlBody: '<p>Click to log in: <a href="{{link}}">Login now</a></p>',
      },
    },
    'alert.critical.system': {
      it: { title: 'ALERT CRITICO', body: '{{message}}', htmlBody: '<strong>{{message}}</strong>' },
      en: { title: 'CRITICAL ALERT', body: '{{message}}', htmlBody: '<strong>{{message}}</strong>' },
      de: { title: 'KRITISCHER ALERT', body: '{{message}}', htmlBody: '<strong>{{message}}</strong>' },
      fr: { title: 'ALERTE CRITIQUE', body: '{{message}}', htmlBody: '<strong>{{message}}</strong>' },
    },
  };

  async render(event: string, payload: Record<string, unknown>, locale: string): Promise<RenderedTemplate> {


…[truncato — apri il file MD per testo completo]