Notificações e gerenciamento de alertas

Esta biblioteca é um conjunto de componentes e hooks para aplicações React, desenvolvida para simplificar a gestão de notificações e o monitoramento de alertas. Ela se integra com a plataforma Novu para fornecer um sistema robusto e personalizável de alerta. Com esta biblioteca, você pode facilmente exibir uma central de alertas pré-definidos e páginas detalhadas para cada política de monitoramento, permitindo que os usuários rastreiem ocorrências, configurem notificações e mantenham-se informados sobre eventos críticos.

Instalação

npm install @4smart/cm-alerts-lib
# ou
pnpm add @4smart/cm-alerts-lib
# ou
yarn add  @4smart/cm-alerts-lib

Uso

Configuração do Provider

Para utilizar a biblioteca, você deve envolver sua aplicação com o NovuNotificationsProvider. Este provider gerencia o estado e as configurações de autenticação e navegação para os componentes de alerta. Adicione-o no arquivo de layout principal, como layout.tsx ou equivalente.

import { NovuNotificationsProvider } from "@4smart/cm-alerts-lib";
import React from "react";
import { useNavigate } from "react-router-dom"; // Exemplo para React Router

const App = ({ children }) => {
  const navigate = useNavigate();
  const token = "YOUR_AUTH_TOKEN"; // Substitua pelo seu token de autenticação
  const municipality = "São Caetano do Sul"; // Use a variável de ambiente associada ao município
  const product = "MOBILITY"; // MOBILTIY | SUSTAINABILITY | EDUCATION
  const applicationIdentifier = "YOUR_APP_IDENTIFIER"; // Identificador Novu

  return (
    <NovuNotificationsProvider
      authToken={token}
      municipality={municipality}
      product={product}
      applicationIdentifier={applicationIdentifier}
      locale="pt-BR" // 'pt-BR' | 'en' | 'es'
      navigate={navigate}
      path="/alert-center"
    >
      {children}
    </NovuNotificationsProvider>
  );
};

export default App;

Observação: A propriedade navigate deve ser a função de roteamento do seu framework. Por exemplo, em uma aplicação Next.js você pode usar useRouter e em uma aplicação React com React Router, use useNavigate.

Configuração de Rota (Obrigatório)

A propriedade path é obrigatória e define o caminho base usado pela biblioteca para navegação:

• path: Caminho base para as páginas de alertas (onde está o componente PredefinedAlertCenter)
• A página de detalhes será automaticamente {path}/:policyId

Esta configuração permite que a biblioteca se adapte ao sistema de roteamento da sua aplicação. Por exemplo:

// Para uma aplicação com rotas simples
path = "/alerts";
// Detalhes serão: /alerts/:policyId

// Para uma aplicação com rotas aninhadas
path = "/dashboard/alerts";
// Detalhes serão: /dashboard/alerts/:policyId

Importante: Certifique-se de que a rota configurada em path corresponde exatamente à rota definida no seu sistema de roteamento.

Internacionalização (i18n)

A biblioteca possui seu próprio sistema de internacionalização totalmente isolado usando react-intl com RawIntlProvider e createIntl. Esta abordagem garante isolamento completo, sem qualquer interferência com sistemas de i18n do aplicativo principal ou outros packages.

Características:

• Isolamento total: Usa RawIntlProvider + createIntl para criar uma instância completamente isolada do react-intl
• Zero conflitos: Não há interferência entre mensagens da biblioteca e do aplicativo principal, mesmo que ambos usem react-intl
• Contexto independente: Cada package pode ter seu próprio IntlProvider sem conflitos de chaves ou mensagens
• Suporte a múltiplos idiomas: Português (pt-BR), Inglês (en) e Espanhol (es)
• Locale configurável: Defina o idioma através da prop locale do NovuNotificationsProvider

Como funciona:

A biblioteca usa createIntl para criar uma instância isolada do intl e RawIntlProvider para fornecer essa instância aos componentes. Diferente do IntlProvider padrão, o RawIntlProvider não usa o contexto global do react-intl, garantindo isolamento total.

Exemplo de uso com aplicativo que possui seu próprio IntlProvider:

import { IntlProvider } from "react-intl";
import { NovuNotificationsProvider } from "@4smart/cm-alerts-lib";

// App principal pode ter seu próprio IntlProvider
<IntlProvider locale="pt-BR" messages={appMessages}>
  {/* Componentes do app principal */}

  {/* Biblioteca cria instância isolada com RawIntlProvider */}
  <NovuNotificationsProvider locale="pt-BR" {...otherProps}>
    {/* Componentes da biblioteca usam apenas suas próprias traduções */}
    {/* Mesmo se ambos usarem a mesma chave (ex: "button.save"), */}
    {/* cada um resolve dentro do seu próprio contexto isolado */}
    <PredefinedAlertCenter />
  </NovuNotificationsProvider>
</IntlProvider>

Idiomas suportados:

• pt-BR - Português (Brasil) - padrão
• en - Inglês
• es - Espanhol

Páginas de Alerta

A biblioteca oferece dois componentes principais de página:

• PredefinedAlertCenter: Uma visão geral de todas as políticas de alerta configuradas, ideal para uma central de monitoramento.
• AlertPolicyDetailsPage: Uma página de detalhes para uma política de alerta específica, exibindo o histórico de ocorrências e outras informações.

Você pode renderizá-los diretamente em suas rotas:

Exemplo de uso

import {
  AlertPolicyDetailsPage,
  PredefinedAlertCenter,
} from "@4smart/cm-alerts-lib";

// Exemplo de uma página de central de alertas
const AlertsPage = () => {
  return <PredefinedAlertCenter />;
};

Central de Alertas Predefinidos

Detalhes do alerta

Roteamento da Página de Detalhes

O botão de ação na tabela de Políticas de alerta configuradas, dentro do componente PredefinedAlertCenter, irá redirecionar automaticamente para o caminho configurado em path seguido do ID da política (ex: /alert-center/:id-da-politica).

É necessário que você crie uma rota em seu projeto seguindo o padrão {path}/:policyId e renderize o componente AlertPolicyDetailsPage nela, passando o policyId obtido dos parâmetros da URL.Exemplo de configuração de rota com React Router:

import { BrowserRouter, Routes, Route, useParams } from "react-router-dom";
import {
  AlertPolicyDetailsPage,
  PredefinedAlertCenter,
} from "@4smart/cm-alerts-lib";

const AlertDetailsWrapper = () => {
  const { policyId } = useParams();
  return <AlertPolicyDetailsPage policyId={policyId} />;
};

function App() {
  return (
    <BrowserRouter>
      <Routes>
        {/* Rota principal de alertas - deve corresponder ao alertCenterPath */}
        <Route path="/alerts" element={<PredefinedAlertCenter />} />

        {/* Rota de detalhes - deve corresponder ao alertDetailsPath/:policyId */}
        <Route
          path="/alert-details/:policyId"
          element={<AlertDetailsWrapper />}
        />
      </Routes>
    </BrowserRouter>
  );
}

Para Next.js com App Router:

// app/alerts/page.tsx
import { PredefinedAlertCenter } from "@4smart/cm-alerts-lib";

export default function AlertsPage() {
  return <PredefinedAlertCenter />;
}

// app/alert-details/[policyId]/page.tsx
import { AlertPolicyDetailsPage } from "@4smart/cm-alerts-lib";

export default function AlertDetailsPage({
  params,
}: {
  params: { policyId: string };
}) {
  return <AlertPolicyDetailsPage policyId={params.policyId} />;
}

Propriedades do NovuNotificationsProvider

| Propriedade | Tipo | Obrigatório | Descrição | | ----------------------- | ------------------------------------------------------- | ----------- | --------------------------------------------------------- | | children | ReactNode | ✅ | Componentes filhos que serão envolvidos pelo provider | | applicationIdentifier | string \| undefined | ✅ | Identificador único da aplicação no Novu | | authToken | string | ✅ | Token de autenticação para as APIs | | municipality | string | ✅ | Nome do município associado | | product | "MOBILITY" \| "SUSTAINABILITY" \| "EDUCATION" | ✅ | Produto da Cloudmatize | | locale | "pt-BR" \| "en" \| "es" | ✅ | Idioma da aplicação | | navigate | (url: string) => void | ✅ | Função de navegação do framework de roteamento | | options | { alertCenterPath: string; alertDetailsPath: string } | ✅ | Configuração de caminhos de roteamento | | duration | number | ❌ | Duração das notificações em milissegundos (padrão: 10000) | | darkMode | boolean | ❌ | Ativa o modo escuro (padrão: false) |

Hook de Notificações

Para interagir com as notificações da aplicação, utilize o hook useNovuNotifications em qualquer componente filho do NovuNotificationsProvider.

import { useNovuNotifications } from "@4smart/cm-alerts-lib";
import React from "react";

const MyComponent = () => {
  const {
    unreadNotificationsCount,
    notificationQueue,
    markAllAsRead,
    removeFromQueue,
    isLoading,
  } = useNovuNotifications();

  return (
    <div>
      {isLoading ? (
        <p>Carregando notificações...</p>
      ) : (
        <>
          <p>Você tem {unreadNotificationsCount} notificações não lidas.</p>
          <button onClick={markAllAsRead}>Marcar todas como lidas</button>
        </>
      )}
    </div>
  );
};

Exemplo da notificação

Dependências

Este projeto depende de React e ReactDOM. Certifique-se de que essas dependências estejam instaladas e configuradas em seu projeto.

Licença

Este projeto está licenciado sob a licença MIT.