@edirect/slack

Slack integration module for eDirect NestJS applications. Provides a configurable SlackService for sending structured messages to Slack channels, with support for message levels (INFO, WARN, ERROR), custom payloads, attributes, and message templates.

Features

• Structured Slack messages with level, sender, cluster, payload, and custom attributes
• Three message levels: INFO, WARN, ERROR
• active flag for disabling Slack notifications without removing code
• silent option for suppressing errors (fire-and-forget)
• Per-call channel override
• Custom template support
• Async configuration with registerAsync
• Integrates with @edirect/config
• Requires a Slack bot token with chat:write scope

Installation

pnpm add @edirect/slack
# or
npm install @edirect/slack

Setup

Register SlackModule in your AppModule

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@edirect/config';
import { SlackModule } from '@edirect/slack';

@Module({
  imports: [
    ConfigModule,
    SlackModule.registerAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        active: configService.get('SLACK_ACTIVE') === 'true',
        service: configService.get('APP_NAME') ?? 'my-service',
        cluster: configService.get('NAMESPACE') ?? 'local',
        slack: {
          token: configService.get('SLACK_TOKEN') as string,
          channel: configService.get('SLACK_CHANNEL') as string,
        },
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Send a message

import { Injectable } from '@nestjs/common';
import { SlackService, MessageLevel } from '@edirect/slack';

@Injectable()
export class AlertService {
  constructor(private readonly slack: SlackService) {}

  async notifyError(error: Error, context: object): Promise<void> {
    await this.slack.sendMessage(
      MessageLevel.ERROR,
      `Unhandled error: ${error.message}`,
      JSON.stringify(context), // optional payload
      { environment: 'production' } // optional custom attributes
    );
  }

  async notifyInfo(message: string): Promise<void> {
    await this.slack.sendMessage(MessageLevel.INFO, message);
  }

  // Send to a different channel
  async notifyOpsChannel(message: string): Promise<void> {
    await this.slack.sendMessage(
      MessageLevel.WARN,
      message,
      undefined,
      undefined,
      '#ops-alerts' // channel override
    );
  }
}

SlackConfig Options

| Option | Type | Required | Description | | --------------- | --------- | -------- | -------------------------------------------------------------------------- | | active | boolean | Yes | Set to true to enable sending messages; false silently skips all sends | | service | string | Yes | Service name shown as the message sender | | cluster | string | Yes | Cluster/namespace shown in messages | | silent | boolean | No | If true, errors from Slack API are swallowed | | slack.token | string | Yes | Slack bot token (requires chat:write scope) | | slack.channel | string | Yes | Default Slack channel ID or name |

MessageLevel Enum

| Value | Description | | -------------------- | ----------------------------- | | MessageLevel.INFO | Informational message (green) | | MessageLevel.WARN | Warning message (yellow) | | MessageLevel.ERROR | Error message (red) |

SlackService.sendMessage()

sendMessage(
  level: MessageLevel,
  message: string,
  payload?: string,
  attributes?: Record<string, string>,
  channel?: string,
  template?: string
): Promise<string | null>

| Parameter | Type | Description | | ------------ | ------------------------ | ---------------------------------------------------- | | level | MessageLevel | Message severity level | | message | string | Main message text | | payload | string | Optional JSON payload or additional details | | attributes | Record<string, string> | Optional key-value pairs shown as additional context | | channel | string | Override the default channel for this message | | template | string | Custom message template name |

Returns the Slack message timestamp (ts) on success, or null if active is false.

Environment Variables

| Variable | Description | | --------------- | --------------------------------------------- | | SLACK_ACTIVE | Set to 'true' to enable Slack notifications | | SLACK_TOKEN | Slack bot OAuth token | | SLACK_CHANNEL | Default Slack channel ID or name |