@somnus_stasis/discord-alert-utils

Reusable utility for sending Discord alerts with throttling, error normalization, and safe formatting. Perfect for cron jobs, workers, or any Node.js service where you want to send structured error notifications to a Discord channel.

🚀 Installation

npm install @somnus_stasis/discord-alert-utils

or with yarn:

yarn add @somnus_stasis/discord-alert-utils

📦 Usage

const { sendDiscordAlert } = require("@somnus_stasis/discord-alert-utils");

async function runJob() {
  try {
    // Your logic here...
    throw new Error("Request failed with status code 401");
  } catch (err) {
    await sendDiscordAlert({
      title: "🚨 My Job Error",
      functionDesc: "Temp Sync Job – Synchronize LMS data (ratings, participants, CPI, occupation, certificates)",
      errorDesc: "Failed to sync endpoint: /db/course-rating/sync",
      time: new Date().toLocaleString("id-ID"),
      errorDetail: err.message,
    });
  }
}

runJob();

🔧 Features

• Discord Embed: Sends alerts as structured Discord embed messages.
• Throttle Duplicate Alerts: Prevents spamming the same error repeatedly within a cooldown window.
• Error Normalization: Cleans up timestamps, UUIDs, and line numbers before hashing.
• Safe Error Length: Automatically truncates long error messages to fit Discord’s 2000-char limit.
• Configurable Cooldown: Adjust alert cooldown with environment variable.

⚙️ Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | DISCORD_WEBHOOK_URL | Discord webhook URL (required) | - | | ALERT_COOLDOWN_MINUTES | Cooldown window for duplicate alerts | 30 |

Example .env:

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/xxxx/xxxx
ALERT_COOLDOWN_MINUTES=30

📌 API

sendDiscordAlert(options)

| Option | Type | Required | Description | |--------|------|----------|-------------| | title | string | ✅ | Title of the alert embed | | functionDesc | string | ✅ | Description of the job/function responsibility | | errorDesc | string | ✅ | Short description of the error | | time | string | ✅ | Timestamp of the error (formatted string) | | errorDetail | string | ✅ | Full error detail (truncated if >2000 chars) |

📝 Example Output

📜 License

MIT © 2025 somnus_stasis