# 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

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

### Configuracion de Paths

```json
{
  "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

```typescript
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

```typescript
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

```typescript
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

```markdown
- [ ] 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