Question

SmartAlert-T (SAT) — Node.js

The first line of defense for your servers and applications.
Send beautiful, structured Telegram alerts — critical, warning, info — straight from your Node.js code, cron jobs and background workers.

Built by Gift Balogun. This is the Node.js twin of the PHP/Laravel SmartAlert-T package — identical message styling and footer across both runtimes.

---

✨ Features

• 🚨 Three alert levels — Critical, Warning, Info — each with distinct emoji + styling.
• 💬 Send to individual users, groups, supergroups and channels.
• 🟦 TypeScript-first — ships with full type definitions.
• ⏱️ Cron & background-process friendly — optional non-throwing mode so alerting never crashes your jobs.
• 🏷️ Rich context metadata block + automatic timestamp.
• 🔒 HTML-safe message escaping.
• 🪶 Zero runtime dependencies — built on the Node.js core https module.
• 🖋️ Branded footer with copyright to Gift Balogun on every message.

---

📦 Installation

npm install smart-alert-t
# or
yarn add smart-alert-t

Requires Node.js >= 14.

---

🤖 Getting your Telegram credentials

1. Create a bot — open @BotFather, send /newbot, and copy the bot token (e.g. 123456789:AAH...).
2. Find your chat id:
   • Personal chat: message @userinfobot for your numeric id.
   • Group: add the bot to the group, then open https://api.telegram.org/bot<TOKEN>/getUpdates and read chat.id (group ids are usually negative).
   • Channel: use @your_channel_username and make the bot an admin.

---

🚀 Quick start

CommonJS

const { SmartAlert } = require('smart-alert-t');

const alert = SmartAlert.make({
  token: 'YOUR_BOT_TOKEN',
  chatId: 'YOUR_CHAT_ID',   // user, group, or @channel
  appName: 'Payments API',  // optional label on every alert
});

await alert.critical('Database down', 'Primary DB is unreachable.', { host: 'db-01' });
await alert.warning('High memory',   'Worker memory at 86%.',       { service: 'queue' });
await alert.info('Deploy complete',  'v2.4.1 shipped to prod.',     { version: '2.4.1' });

ES Modules / TypeScript

import { SmartAlert } from 'smart-alert-t';

const alert = new SmartAlert({
  token: process.env.SMART_ALERT_TOKEN!,
  chatId: process.env.SMART_ALERT_CHAT_ID!,
  appName: 'Billing Service',
});

await alert.info('Job done', 'Nightly export completed.', { rows: 48211 });

---

🎨 The three alert types

Method	Emoji	Use it for
critical()	🚨	Outages, data loss, anything paging-worthy
warning()	⚠️	Degraded state that needs attention soon
info()	ℹ️	Deploys, job completions, routine heads-up

Every method shares the same signature and returns a Promise:

alert.critical(
  title: string,                       // short headline
  message: string,                     // body text
  context?: Record<string, unknown>,   // optional metadata block
  chatId?: string | number | null,     // optional per-call destination override
): Promise<SmartAlertResult>;

A rendered alert looks like:

🚨 [CRITICAL] Database down
App: Payments API

Primary DB is unreachable.

• host: db-01
• region: eu-west-1

🕒 2026-06-03 10:42:11 UTC
Powered by SmartAlert-T © 2026 — Gift Balogun

---

👥 Sending to users vs. groups vs. channels

The destination is just the chatId:

// Individual user
await alert.info('Hi', 'Personal message.', {}, 123456789);

// Group / supergroup (ids are typically negative)
await alert.warning('Heads up', 'Group message.', {}, -1001234567890);

// Public channel
await alert.critical('Outage', 'Channel broadcast.', {}, '@my_status_channel');

Set a default chatId in the constructor and override it per call only when needed.

---

⏰ Using it in cron jobs & background processes

Set throwOnError: false so a transient Telegram hiccup can never crash your scheduled task — the promise resolves to { ok: false, error } instead of rejecting.

const os = require('os');
const { SmartAlert } = require('smart-alert-t');

const alert = SmartAlert.make({
  token: process.env.SMART_ALERT_TOKEN,
  chatId: process.env.SMART_ALERT_CHAT_ID,
  appName: `Server: ${os.hostname()}`,
  throwOnError: false,
});

const result = await alert.warning('Disk filling up', 'Root volume at 82%.', { used: '82%' });
if (!result.ok) {
  console.error('[SAT] delivery failed:', result.error);
}

Crontab example (every 5 minutes):

SMART_ALERT_TOKEN=123456789:AAH...
SMART_ALERT_CHAT_ID=-1001234567890
*/5 * * * * /usr/bin/node /var/www/app/examples/cron-health-check.js >> /var/log/sat.log 2>&1

node-cron example:

const cron = require('node-cron');
const { SmartAlert } = require('smart-alert-t');

const alert = SmartAlert.make({
  token: process.env.SMART_ALERT_TOKEN,
  chatId: process.env.SMART_ALERT_CHAT_ID,
  throwOnError: false,
});

cron.schedule('*/5 * * * *', async () => {
  // your health check...
  await alert.info('Heartbeat', 'Service is alive.');
});

See examples/basic-usage.js, examples/cron-health-check.js and examples/typescript-usage.ts for complete scripts.

---

⚙️ Configuration reference

Option	Type	Default	Description
token	string	—	Telegram bot token from @BotFather. Required.
chatId	string \| number \| null	null	Default destination (user/group/@channel).
appName	string \| null	null	Optional label shown on every alert.
timeout	number	10000	Request timeout in milliseconds.
throwOnError	boolean	true	Reject on failure (true) or resolve an error payload.

---

🛡️ Error handling

Default mode rejects with a SmartAlertError:

const { SmartAlert, SmartAlertError } = require('smart-alert-t');

try {
  await alert.critical('X', 'Y');
} catch (err) {
  if (err instanceof SmartAlertError) {
    // log, retry, fall back to email, ...
  }
}

With throwOnError: false, every call resolves to { ok: false, error } on failure and the decoded Telegram response on success.

---

🧪 Testing & building

npm install
npm run build   # compile TypeScript -> dist/
npm test        # run the offline unit tests

The test suite covers alert-type validation, message formatting, HTML escaping and error handling — all without network calls.

---

📄 License

MIT © Gift Balogun

---