onroad-plugins-sign (Notification Engine V2)

Plugin NPM do ecossistema OnRoad (TypeScript) que estandardiza as implementações da Engine de Notificações. Responsável por tipar o envio das interações para a Notification API (via RMQ notification.trigger.queue).

Como Instalar (Num projeto OnRoad)

1. Adicione a biblioteca ao seu package.json e baixe as atualizações localmente.
2. Certifique-se de definir as variáveis de ambiente necessárias (como a NOTIFICATION_API_URL caso deseje utilizar cancelamento/reschedule).

Tutorial de Utilização

1. Declare o seu Dicionário Estrito de Templates

Defina as regras e modelos de notificação específicos à sua Micro-API (ex: api-processo, api-financeiro). Cada chave será imposta via Type-Safety quando instanciar o serviço.

import { INotificationTemplate } from "onroad-plugins-sign"

export const MY_API_TEMPLATES = {
  REGISTRO_VENCIDO: {
    messageTemplate: "O controle '{{nomeParametro}}' está com {{diasAtraso}} dia(s) de atraso.",
    title: "Registro Vencido",
    tipo: "REGISTRO_VENCIDO",
    context: "controle",
  },
  ALARME_INCENDIO: {
    messageTemplate: "Fogo detetado no setor {{setor}}!!",
    title: "EMERGÊNCIA!",
    tipo: "EMERGENCIA_INCENDIO",
    context: "setor_seguranca",
  }
} as const satisfies Record<string, INotificationTemplate>;

// Derive o Type nativo das suas chaves (apenas para organização própria)
export type MyTemplatesKey = keyof typeof MY_API_TEMPLATES;

2. Inicie o Engine Service com Auto-Mapping (Dependency Injection)

Em qualquer Controller / Service da sua aplicação em que precise disparar notificações, instancie o serviço injetando o seu Dicionário como Genérico. Pode passar o Contexto sentinel base do OnRoadExpress para herança de instâncias RabbitMQ (globalAgent).

import { NotificationTriggerService } from "onroad-plugins-sign"
import { MY_API_TEMPLATES } from './NotificationTemplates';

export class MeuServicoCustomizado {
  public triggerSVC: NotificationTriggerService<typeof MY_API_TEMPLATES>;

  constructor(sentinel: any) {
    // Injeta os templates e assume as types das chaves declaradas (REGISTRO_VENCIDO e ALARME_INCENDIO)
    this.triggerSVC = new NotificationTriggerService(sentinel, MY_API_TEMPLATES);
  }

  async testarFogo() {
    // 💡 O TypeScript VAI OBRIGAR-TE a usar APENAS as chaves pré-registadas nesta API! (ex: ALARME_INCENDIO)
    // O TypeScript NÃO VAI deixar passar `REGISRRR_ERRO`!
    await this.triggerSVC.trigger("ALARME_INCENDIO", "TeraproxTenant", "Setor4", {
      setor: "Almoxarifado B" 
    });
  }
}

3. Agendamentos "Ad-Hoc" (Dead Man's Switch / Disjuntor)

Se a sua notificação não é de disparo imediato, mas serve como um Alerta Temporário (Scheduled), injete em options:

// Agenda um alarme para daqui a 60 minutos (milliseconds: 3600000)
await this.triggerSVC.trigger(
  "REGISTRO_VENCIDO",       // TemplateKey
  "tenant-id",              // Tenant
  "context-123",            // ContextId
  { nomeParametro: "pH", diasAtraso: 0 }, 
  { 
    milliseconds: 3600000, 
    start_date: new Date(Date.now() + 3600000).toISOString(),
    context: "registro_custom" // Sobrescreve o default 'context' do template
  }
);

4. Cancelamentos

Se o utlizador desativar o cenário acima (ex: preencheu o formulário a tempo), aborte o trigger Scheduled na Notification API:

// MATA o alerta agendado, utilizando a Chave original e os identificadores que foram salvos.
await this.triggerSVC.cancel("REGISTRO_VENCIDO", "tenant-id", "context-123", { context: "registro_custom" });