@getsupervisor/battle-arena-notifications-ui

Centro de notificaciones React aislado y portable: campana con badge, panel con feed, botonera por notificación y actualización en vivo por SSE. Cero dependencias de runtime más allá de React (sin MUI, sin react-query): estilos inline tematizables por tokens.

Es el cliente de referencia del módulo backend apps/public-api/src/notifications (cualquier backend que implemente ese contrato REST+SSE sirve).

Uso

import {
  NotificationsProvider,
  NotificationBell,
} from '@getsupervisor/battle-arena-notifications-ui';

<NotificationsProvider
  baseUrl="https://mi-api.com/v1" // prefijo donde vive /notifications
  recipient="[email protected]" // identificador del destinatario
  apiKey="opcional" // viaja como ?apiKey= (EventSource no admite headers)
  theme={{ accent: '#8b6cf6', panel: '#161922' }} // tokens de tu marca (todo opcional)
  labels={{ title: 'Notificaciones' }} // textos (i18n/whitelabel)
  onIncoming={(n) => toast(n.title)} // notificación llegando en vivo (tus toasts)
  onNavigate={(href) => router.push(href)} // acciones CON href (deep-links del template)
  onAction={(n, action) => {
    // acciones SIN href (callback por key)
    if (action.key === 'decline_challenge')
      declineChallenge(n.data.challengeId);
  }}
>
  <NotificationBell />
</NotificationsProvider>;

Integración real de ejemplo: apps/web/src/components/organisms/ArenaNotifications/ (teñido con el theme MUI del arena, toasts con notistack, navegación con next/router).

Piezas exportadas

• NotificationsProvider / useNotifications() — estado del feed (items, unread, open), acciones (markRead, markAllRead, runAction) y conexión SSE (auto-reconexión del EventSource nativo).
• NotificationBell — campana + badge + dropdown anclado (cierra con click afuera).
• NotificationCenter, NotificationItem — usables sueltos si quieres tu propio anclaje (p. ej. página de historial).
• NotificationsClient — cliente HTTP+SSE sin React, por si integras con otro framework.
• feedReducer — reducer puro del estado (testeable).

Contrato esperado del backend

• GET {baseUrl}/notifications?recipient=&limit= → { items: Notification[], unread: number }
• GET {baseUrl}/notifications/stream?recipient= → SSE con frames event: notification y el JSON de la notificación en data:.
• POST {baseUrl}/notifications/:id/read · POST .../read-all ({recipient}) · POST .../:id/archive

Notification: ver src/types.ts (id, recipient, templateKey, category, icon, title, body, actions[], data, status, createdAt, readAt). La botonera viene YA renderizada del template del backend: la lib solo la pinta y enruta (href → onNavigate; sin href → onAction).

Portar a otro proyecto

1. Copia la carpeta apps/notifications-ui (o publícala en tu registry) y agrégala a los workspaces. yarn build genera dist/ (tsup, ESM+CJS+tipos).
2. El consumidor agrega "@getsupervisor/battle-arena-notifications-ui": "0.1.0" (renómbrala si quieres).
3. Monta el Provider donde el destinatario sea conocido (post-login) y la campana en tu header.
4. Tematiza con theme (tokens en src/theme.ts) y traduce con labels.

Desarrollo

yarn test        # jest (jsdom): reducer, relativeTime, render con botonera
yarn typecheck   # tsc --noEmit
yarn build       # tsup → dist/