workspace-v1/shared/modules/notifications/README.md

Notifications - Core Module

Modulo: shared/modules/notifications/ Version: 0.1.0 Fecha: 2026-01-03 Owner: Backend-Agent Estado: desarrollo

---

Descripcion

Modulo de notificaciones compartido que provee servicios para envio de emails, push notifications e in-app notifications. Abstrae los proveedores de notificacion para uso unificado en todos los proyectos.

---

Instalacion

Prerequisitos

npm install nodemailer @nestjs/mailer
npm install -D @types/nodemailer
# Opcional para push:
npm install firebase-admin

Configuracion de Paths

{
  "compilerOptions": {
    "paths": {
      "@shared/modules/*": ["../../shared/modules/*"]
    }
  }
}

---

API Publica (Planificada)

Servicios

Servicio	Descripcion	Canales
NotificationService	Servicio principal unificado	email, push, in-app
EmailService	Envio de emails	SMTP, SES
PushService	Push notifications	FCM, APNs
InAppService	Notificaciones in-app	WebSocket, polling

Tipos

interface Notification {
  id: string;
  userId: string;
  type: 'email' | 'push' | 'in-app';
  title: string;
  body: string;
  data?: Record<string, any>;
  status: 'pending' | 'sent' | 'failed' | 'read';
  createdAt: Date;
  sentAt?: Date;
  readAt?: Date;
}

interface NotificationPreferences {
  userId: string;
  email: boolean;
  push: boolean;
  inApp: boolean;
  categories: Record<string, boolean>;
}

---

Ejemplos de Uso

Ejemplo 1: Enviar Notificacion

import { NotificationService } from '@shared/modules/notifications';

@Injectable()
export class OrderService {
  constructor(private notifications: NotificationService) {}

  async createOrder(order: Order) {
    // ... crear orden

    await this.notifications.send({
      userId: order.userId,
      type: 'email',
      title: 'Orden Confirmada',
      body: `Tu orden #${order.id} ha sido confirmada`,
      template: 'order-confirmation',
      data: { order },
    });
  }
}

Ejemplo 2: Notificacion Multi-canal

await this.notifications.sendMulti({
  userId: user.id,
  channels: ['email', 'push', 'in-app'],
  title: 'Nuevo Mensaje',
  body: 'Tienes un nuevo mensaje',
  respectPreferences: true,  // Respetar preferencias del usuario
});

---

Dependencias

Internas

Modulo	Uso
@shared/modules/utils	Formateo, validaciones

Externas (npm)

Paquete	Version	Uso
nodemailer	^6.9	Envio SMTP
@nestjs/mailer	^1.9	Integracion NestJS
firebase-admin	^11.0	Push FCM (opcional)

---

Relacion con Catalogo

Aspecto	modules/notifications	catalog/notifications
Contenido	Servicios listos	Documentacion + DDL
Uso	Importar directamente	Copiar y adaptar
DDL	No incluye	Incluye tablas

---

Estado Actual

- [ ] NotificationService base
- [ ] EmailService con nodemailer
- [ ] PushService con FCM
- [ ] InAppService con eventos
- [ ] Template engine
- [ ] Preferencias de usuario
- [ ] Tests unitarios
- [ ] Documentacion completa

---

Changelog

v0.1.0 (2026-01-03)

• Estructura inicial
• README con planificacion

---

Modulo: shared/modules/notifications/ | Owner: Backend-Agent