npm package: @marssaljr/cm-alerts-lib
Description: 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 aler
Latest version: 1.0.142

# 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

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

## Teste local 
1. Adicionado noExternal: ["react-icons", "@tanstack/react-query", "lucide-react"] no tsup.config.ts
2. Feito build e npm pack
3. Installado com npm (pnpm estava com problemas)

## 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.

```tsx
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:

```tsx
// 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:**

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

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

![Central de Alertas Predefinidos](public/AlertPolicyDetailsPage.png)

### Detalhes do alerta

![Detalhes do alerta](public/PredefinedAlertCenter.png)

#### 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:

```tsx
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:**

```tsx
// 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**.

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

![Exemplo de notificação](public/notification-example.png)

## 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.