@menumalsuite/nestjs-slack-alerts

Modulo NestJS per mandare alert Slack formattati con Block Kit, con header progetto | env | servizio.

❌ MenuAPI | Prod | Whatsapp
Failed to send WhatsApp message

phone                  part
+39...                 1/2

Installazione

npm install @menumalsuite/nestjs-slack-alerts @slack/web-api

Peer dependencies: @nestjs/common ^10 || ^11, @slack/web-api ^7.

Configurazione

import { SlackAlertsModule } from '@menumalsuite/nestjs-slack-alerts';

@Module({
	imports: [
		SlackAlertsModule.forRootAsync({
			isGlobal: true,
			inject: [ConfigService],
			useFactory: (config: ConfigService) => ({
				projectName: config.get('app.name'),
				environment: config.get('node_env'),
				token: config.get('slack.token'),
				defaultChannel: 'alerts',
				channels: {
					alerts: { id: config.get('slack.channel') },
					sales: { id: config.get('slack.sales_channel') },
					support: { id: config.get('slack.support_channel') },
				},
				enabled: config.get('slack.alerts_enabled'),
			}),
		}),
	],
})
export class AppModule {}

SlackAlertsModule.forRoot/forRootAsync va registrato una sola volta per applicazione, tipicamente nel modulo radice. Passare isGlobal: true è il modo con cui i moduli di feature ottengono SlackAlertsService senza reimportare SlackAlertsModule ognuno per conto proprio.

Uso

constructor(private readonly slack: SlackAlertsService) {}

await this.slack.sendAlert({
	service: 'Whatsapp',
	severity: 'error',
	title: 'Failed to send WhatsApp message',
	fields: { phone, part: '1/2' },
	error,
});

await this.slack.sendAlert(alert, 'sales');
await this.slack.sendThreadReply(alert, threadTs, 'support');

Opzioni

| Opzione | Tipo | Default | Descrizione | |---|---|---|---| | projectName | string | — | Prima parte dell'header | | environment | string | — | Ambiente grezzo, es. NODE_ENV. Non può essere vuoto o solo spazi | | envLabels | Record<string, string> | mappa interna | Override delle etichette di ambiente | | token | string | — | Bot token di default | | channels | Record<string, { id, token? }> | — | Canali indirizzati per chiave | | defaultChannel | string | — | Chiave usata da sendAlert senza canale | | enabled | boolean | true | A false nessuna chiamata di rete. Deve essere un booleano | | dedupWindowMs | number | 300000 | 0 disattiva il dedup. Deve essere un numero finito e non negativo | | isGlobal | boolean | false | Registra il modulo come globale |

Etichette di ambiente di default: production → Prod, staging → Staging, development → Dev, local → Local, test → Test. Un valore sconosciuto viene capitalizzato.

Comportamento

• sendAlert non lancia mai su errore di invio: ritorna undefined e logga il codice Slack
• Una chiave di canale sconosciuta viene loggata (con la chiave e le chiavi note) e saltata, non lancia: ritorna undefined senza tentare l'invio
• La configurazione invalida lancia al bootstrap, non a runtime
• Quando enabled è false il modulo è completamente inerte: nessuna chiamata di rete e nessuna validazione del canale, nemmeno se la chiave passata non esiste in configurazione
• Alert identici (canale | servizio | severity | titolo) vengono consegnati una volta per finestra; la consegna successiva riporta (+N duplicates suppressed)
• Il dedup tiene al massimo 500 chiavi in memoria: quando lo spazio finisce, la voce meno recente viene rimossa e il suo conteggio di duplicati soppressi va perso; se quella stessa chiave ricompare in seguito riparte da zero
• Ogni valore dinamico è escapato per mrkdwn e troncato ai limiti Slack
• unfurl_links e unfurl_media sono sempre disattivati

Export aggiuntivi

Le funzioni pure sono esportate anche singolarmente, per chi vuole solo formattare: buildAlertMessage, escapeMrkdwn, truncate, formatLink, serializeError, resolveEnvLabel, AlertDeduplicator.

• SLACK_ALERTS_OPTIONS — il token di dependency injection delle opzioni, utile per sovrascrivere il provider nei test di chi consuma il pacchetto
• validateOptions — valida un oggetto di configurazione, utile nei test propri di chi consuma il pacchetto
• extractSlackErrorCode — estrae il codice di errore dell'API Slack da un valore lanciato
• DEFAULT_DEDUP_WINDOW_MS — la finestra di dedup di default, in millisecondi

Licenza

Il pacchetto è distribuito con licenza UNLICENSED. È pubblicato su npm pubblicamente solo per comodità di installazione, non per concedere a terzi il diritto di utilizzo.

Design

Vedi docs/specs/2026-08-04-nestjs-slack-alerts-design.md e docs/plans/2026-08-04-nestjs-slack-alerts.md.