smart-alert-t 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gift Balogun (https://giftbalogun.name.ng/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# 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.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D14-339933.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6.svg)](https://www.typescriptlang.org/)
+
+Built by **[Gift Balogun](https://giftbalogun.name.ng/)**. 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
+
+```bash
+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](https://t.me/BotFather), send `/newbot`, and copy the **bot token** (e.g. `123456789:AAH...`).
+2. **Find your chat id:**
+   - **Personal chat**: message [@userinfobot](https://t.me/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
+
+```js
+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
+
+```ts
+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`:
+
+```ts
+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`:
+
+```js
+// 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.
+
+```js
+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):
+
+```cron
+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:**
+
+```js
+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/basic-usage.js), [`examples/cron-health-check.js`](examples/cron-health-check.js) and [`examples/typescript-usage.ts`](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`:
+
+```js
+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
+
+```bash
+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](https://giftbalogun.name.ng/)
+
+---
+
+<p align="center"><sub>Powered by SmartAlert-T (SAT) — built with ❤️ by <a href="https://giftbalogun.name.ng/">Gift Balogun</a></sub></p>

package/dist/alertType.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Defines the supported SmartAlert-T alert types and their visual styling.
+ *
+ * Each alert type maps to an emoji and a human readable label that is used to
+ * build a consistent, easily scannable Telegram message. The styling mirrors
+ * the PHP version of SmartAlert-T so alerts look identical across runtimes.
+ *
+ * @author Gift Balogun <https://giftbalogun.name.ng/>
+ */
+export type AlertTypeValue = 'critical' | 'warning' | 'info';
+export declare const AlertType: {
+    CRITICAL: "critical";
+    WARNING: "warning";
+    INFO: "info";
+    /** Return all valid alert type identifiers. */
+    all(): AlertTypeValue[];
+    /** Determine whether the given type is supported. */
+    isValid(type: string): type is AlertTypeValue;
+    /** Get the emoji associated with an alert type. */
+    emoji(type: string): string;
+    /** Get the upper-cased label associated with an alert type. */
+    label(type: string): string;
+};

package/dist/alertType.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Defines the supported SmartAlert-T alert types and their visual styling.
+ *
+ * Each alert type maps to an emoji and a human readable label that is used to
+ * build a consistent, easily scannable Telegram message. The styling mirrors
+ * the PHP version of SmartAlert-T so alerts look identical across runtimes.
+ *
+ * @author Gift Balogun <https://giftbalogun.name.ng/>
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlertType = void 0;
+const STYLES = {
+    critical: { emoji: '🚨', label: 'CRITICAL' },
+    warning: { emoji: '⚠️', label: 'WARNING' },
+    info: { emoji: 'ℹ️', label: 'INFO' },
+};
+exports.AlertType = {
+    CRITICAL: 'critical',
+    WARNING: 'warning',
+    INFO: 'info',
+    /** Return all valid alert type identifiers. */
+    all() {
+        return Object.keys(STYLES);
+    },
+    /** Determine whether the given type is supported. */
+    isValid(type) {
+        return Object.prototype.hasOwnProperty.call(STYLES, String(type).toLowerCase());
+    },
+    /** Get the emoji associated with an alert type. */
+    emoji(type) {
+        var _a, _b;
+        const key = String(type).toLowerCase();
+        return (_b = (_a = STYLES[key]) === null || _a === void 0 ? void 0 : _a.emoji) !== null && _b !== void 0 ? _b : STYLES.info.emoji;
+    },
+    /** Get the upper-cased label associated with an alert type. */
+    label(type) {
+        var _a, _b;
+        const key = String(type).toLowerCase();
+        return (_b = (_a = STYLES[key]) === null || _a === void 0 ? void 0 : _a.label) !== null && _b !== void 0 ? _b : STYLES.info.label;
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SmartAlert-T (SAT) — Telegram alerting for Node.js.
+ *
+ * The first line of defense for your servers and applications.
+ *
+ * @author  Gift Balogun <https://giftbalogun.name.ng/>
+ * @license MIT
+ */
+export { SmartAlert, SmartAlertError } from './smartAlert';
+export type { SmartAlertConfig, SmartAlertResult } from './smartAlert';
+export { AlertType } from './alertType';
+export type { AlertTypeValue } from './alertType';
+export { MessageFormatter } from './messageFormatter';
+export type { AlertContext } from './messageFormatter';
+import { SmartAlert } from './smartAlert';
+export default SmartAlert;

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * SmartAlert-T (SAT) — Telegram alerting for Node.js.
+ *
+ * The first line of defense for your servers and applications.
+ *
+ * @author  Gift Balogun <https://giftbalogun.name.ng/>
+ * @license MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageFormatter = exports.AlertType = exports.SmartAlertError = exports.SmartAlert = void 0;
+var smartAlert_1 = require("./smartAlert");
+Object.defineProperty(exports, "SmartAlert", { enumerable: true, get: function () { return smartAlert_1.SmartAlert; } });
+Object.defineProperty(exports, "SmartAlertError", { enumerable: true, get: function () { return smartAlert_1.SmartAlertError; } });
+var alertType_1 = require("./alertType");
+Object.defineProperty(exports, "AlertType", { enumerable: true, get: function () { return alertType_1.AlertType; } });
+var messageFormatter_1 = require("./messageFormatter");
+Object.defineProperty(exports, "MessageFormatter", { enumerable: true, get: function () { return messageFormatter_1.MessageFormatter; } });
+const smartAlert_2 = require("./smartAlert");
+exports.default = smartAlert_2.SmartAlert;

package/dist/messageFormatter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Optional key/value metadata attached to an alert.
+ */
+export type AlertContext = Record<string, unknown>;
+/**
+ * Builds the final Telegram message body for an alert.
+ *
+ * Produces HTML formatted messages (Telegram "HTML" parse mode) with a
+ * consistent header, optional context block and a branded footer. The exact
+ * same layout is mirrored in the PHP version of SmartAlert-T.
+ *
+ * @author Gift Balogun <https://giftbalogun.name.ng/>
+ */
+export declare class MessageFormatter {
+    static readonly AUTHOR = "Gift Balogun";
+    static readonly AUTHOR_URL = "https://giftbalogun.name.ng/";
+    /**
+     * Format an alert into a Telegram-ready HTML string.
+     */
+    format(type: string, title: string, message: string, context?: AlertContext, appName?: string | null): string;
+    /** Convert any context value to a readable string. */
+    private stringify;
+    /** Human readable UTC timestamp. */
+    private timestamp;
+    /** Escape user supplied content for the Telegram HTML parse mode. */
+    private escape;
+}

package/dist/messageFormatter.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageFormatter = void 0;
+const alertType_1 = require("./alertType");
+/**
+ * Builds the final Telegram message body for an alert.
+ *
+ * Produces HTML formatted messages (Telegram "HTML" parse mode) with a
+ * consistent header, optional context block and a branded footer. The exact
+ * same layout is mirrored in the PHP version of SmartAlert-T.
+ *
+ * @author Gift Balogun <https://giftbalogun.name.ng/>
+ */
+class MessageFormatter {
+    /**
+     * Format an alert into a Telegram-ready HTML string.
+     */
+    format(type, title, message, context = {}, appName) {
+        const emoji = alertType_1.AlertType.emoji(type);
+        const label = alertType_1.AlertType.label(type);
+        const lines = [];
+        let header = `${emoji} <b>[${label}]</b>`;
+        if (title && title.length > 0) {
+            header += ` ${this.escape(title)}`;
+        }
+        lines.push(header);
+        if (appName) {
+            lines.push(`<b>App:</b> ${this.escape(appName)}`);
+        }
+        lines.push('');
+        lines.push(this.escape(message));
+        const entries = Object.entries(context || {});
+        if (entries.length > 0) {
+            lines.push('');
+            for (const [key, value] of entries) {
+                lines.push(`• <b>${this.escape(key)}:</b> ${this.escape(this.stringify(value))}`);
+            }
+        }
+        lines.push('');
+        lines.push(`<i>🕒 ${this.escape(this.timestamp())}</i>`);
+        lines.push(`<i>Powered by SmartAlert-T © ${new Date().getFullYear()} — ` +
+            `<a href="${MessageFormatter.AUTHOR_URL}">${MessageFormatter.AUTHOR}</a></i>`);
+        return lines.join('\n');
+    }
+    /** Convert any context value to a readable string. */
+    stringify(value) {
+        if (value === null || value === undefined) {
+            return '';
+        }
+        if (typeof value === 'boolean') {
+            return value ? 'true' : 'false';
+        }
+        if (typeof value === 'object') {
+            try {
+                return JSON.stringify(value);
+            }
+            catch {
+                return String(value);
+            }
+        }
+        return String(value);
+    }
+    /** Human readable UTC timestamp. */
+    timestamp() {
+        const d = new Date();
+        const pad = (n) => String(n).padStart(2, '0');
+        return (`${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ` +
+            `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())} UTC`);
+    }
+    /** Escape user supplied content for the Telegram HTML parse mode. */
+    escape(value) {
+        return String(value)
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;');
+    }
+}
+exports.MessageFormatter = MessageFormatter;
+MessageFormatter.AUTHOR = 'Gift Balogun';
+MessageFormatter.AUTHOR_URL = 'https://giftbalogun.name.ng/';

package/dist/smartAlert.d.ts

@@ -0,0 +1,71 @@
+import { AlertContext } from './messageFormatter';
+/**
+ * Configuration options for {@link SmartAlert}.
+ */
+export interface SmartAlertConfig {
+    /** Telegram bot token from @BotFather. Required. */
+    token: string;
+    /** Default destination: user id, group id (often negative) or "@channel". */
+    chatId?: string | number | null;
+    /** Optional application/service name shown on every alert. */
+    appName?: string | null;
+    /** Request timeout in milliseconds. Default: 10000. */
+    timeout?: number;
+    /** When true (default) failures reject the promise; when false they resolve to an error payload. */
+    throwOnError?: boolean;
+}
+/**
+ * Result returned by the Telegram API (or an error payload in non-throwing mode).
+ */
+export interface SmartAlertResult {
+    ok: boolean;
+    error?: string;
+    description?: string;
+    result?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Error thrown for any SmartAlert-T configuration or transport failure.
+ */
+export declare class SmartAlertError extends Error {
+    constructor(message: string);
+}
+/**
+ * SmartAlert-T (SAT)
+ *
+ * A lightweight Telegram alerting client — the first line of defense for your
+ * servers and applications. Send CRITICAL, WARNING and INFO alerts to Telegram
+ * users or groups directly from Node.js, cron jobs or background workers.
+ *
+ * Built on the Node.js core `https` module — zero runtime dependencies.
+ *
+ * @author  Gift Balogun <https://giftbalogun.name.ng/>
+ * @license MIT
+ */
+export declare class SmartAlert {
+    static readonly VERSION = "1.0.0";
+    private static readonly API_BASE;
+    private readonly token;
+    private readonly defaultChatId;
+    private readonly appName;
+    private readonly timeout;
+    private readonly throwOnError;
+    private readonly formatter;
+    constructor(config: SmartAlertConfig);
+    /** Convenience factory. */
+    static make(config: SmartAlertConfig): SmartAlert;
+    /** Send a CRITICAL alert (🚨). */
+    critical(title: string, message: string, context?: AlertContext, chatId?: string | number | null): Promise<SmartAlertResult>;
+    /** Send a WARNING alert (⚠️). */
+    warning(title: string, message: string, context?: AlertContext, chatId?: string | number | null): Promise<SmartAlertResult>;
+    /** Send an INFO alert (ℹ️). */
+    info(title: string, message: string, context?: AlertContext, chatId?: string | number | null): Promise<SmartAlertResult>;
+    /**
+     * Send an alert of an arbitrary (validated) type.
+     */
+    send(type: string, title: string, message: string, context?: AlertContext, chatId?: string | number | null): Promise<SmartAlertResult>;
+    /** Build a failure result (throwing or resolving based on config). */
+    private fail;
+    /** Perform the HTTPS request to the Telegram Bot API. */
+    private dispatch;
+}

package/dist/smartAlert.js

@@ -0,0 +1,175 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SmartAlert = exports.SmartAlertError = void 0;
+const https = __importStar(require("https"));
+const url_1 = require("url");
+const alertType_1 = require("./alertType");
+const messageFormatter_1 = require("./messageFormatter");
+/**
+ * Error thrown for any SmartAlert-T configuration or transport failure.
+ */
+class SmartAlertError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SmartAlertError';
+    }
+}
+exports.SmartAlertError = SmartAlertError;
+/**
+ * SmartAlert-T (SAT)
+ *
+ * A lightweight Telegram alerting client — the first line of defense for your
+ * servers and applications. Send CRITICAL, WARNING and INFO alerts to Telegram
+ * users or groups directly from Node.js, cron jobs or background workers.
+ *
+ * Built on the Node.js core `https` module — zero runtime dependencies.
+ *
+ * @author  Gift Balogun <https://giftbalogun.name.ng/>
+ * @license MIT
+ */
+class SmartAlert {
+    constructor(config) {
+        var _a, _b, _c, _d, _e;
+        this.token = (_a = config === null || config === void 0 ? void 0 : config.token) !== null && _a !== void 0 ? _a : '';
+        this.defaultChatId = (_b = config === null || config === void 0 ? void 0 : config.chatId) !== null && _b !== void 0 ? _b : null;
+        this.appName = (_c = config === null || config === void 0 ? void 0 : config.appName) !== null && _c !== void 0 ? _c : null;
+        this.timeout = (_d = config === null || config === void 0 ? void 0 : config.timeout) !== null && _d !== void 0 ? _d : 10000;
+        this.throwOnError = (_e = config === null || config === void 0 ? void 0 : config.throwOnError) !== null && _e !== void 0 ? _e : true;
+        this.formatter = new messageFormatter_1.MessageFormatter();
+        if (!this.token) {
+            throw new SmartAlertError('SmartAlert-T: a Telegram bot token is required. Create one with @BotFather.');
+        }
+    }
+    /** Convenience factory. */
+    static make(config) {
+        return new SmartAlert(config);
+    }
+    /** Send a CRITICAL alert (🚨). */
+    critical(title, message, context = {}, chatId) {
+        return this.send(alertType_1.AlertType.CRITICAL, title, message, context, chatId);
+    }
+    /** Send a WARNING alert (⚠️). */
+    warning(title, message, context = {}, chatId) {
+        return this.send(alertType_1.AlertType.WARNING, title, message, context, chatId);
+    }
+    /** Send an INFO alert (ℹ️). */
+    info(title, message, context = {}, chatId) {
+        return this.send(alertType_1.AlertType.INFO, title, message, context, chatId);
+    }
+    /**
+     * Send an alert of an arbitrary (validated) type.
+     */
+    async send(type, title, message, context = {}, chatId) {
+        if (!alertType_1.AlertType.isValid(type)) {
+            return this.fail(`SmartAlert-T: invalid alert type '${type}'. Use one of: ${alertType_1.AlertType.all().join(', ')}.`);
+        }
+        const target = chatId !== null && chatId !== void 0 ? chatId : this.defaultChatId;
+        if (target === null || target === undefined || target === '') {
+            return this.fail('SmartAlert-T: no chat id provided. Pass one explicitly or set a default chatId.');
+        }
+        const text = this.formatter.format(type, title, message, context, this.appName);
+        return this.dispatch(target, text);
+    }
+    /** Build a failure result (throwing or resolving based on config). */
+    fail(error, extra = {}) {
+        if (this.throwOnError) {
+            return Promise.reject(new SmartAlertError(error));
+        }
+        return Promise.resolve({ ok: false, error, ...extra });
+    }
+    /** Perform the HTTPS request to the Telegram Bot API. */
+    dispatch(chatId, text) {
+        return new Promise((resolve, reject) => {
+            const endpoint = new url_1.URL(`${SmartAlert.API_BASE}/bot${this.token}/sendMessage`);
+            const body = JSON.stringify({
+                chat_id: chatId,
+                text,
+                parse_mode: 'HTML',
+                disable_web_page_preview: true,
+            });
+            const options = {
+                method: 'POST',
+                hostname: endpoint.hostname,
+                path: endpoint.pathname + endpoint.search,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Content-Length': Buffer.byteLength(body),
+                },
+                timeout: this.timeout,
+            };
+            const settle = (err, extra = {}) => {
+                if (this.throwOnError) {
+                    reject(new SmartAlertError(err));
+                }
+                else {
+                    resolve({ ok: false, error: err, ...extra });
+                }
+            };
+            const req = https.request(options, (res) => {
+                let data = '';
+                res.on('data', (chunk) => (data += chunk));
+                res.on('end', () => {
+                    var _a;
+                    let parsed = null;
+                    try {
+                        parsed = JSON.parse(data);
+                    }
+                    catch {
+                        settle(`SmartAlert-T: unexpected Telegram response (HTTP ${res.statusCode}).`, {
+                            raw: data,
+                        });
+                        return;
+                    }
+                    if (!parsed.ok) {
+                        settle(`SmartAlert-T: Telegram API error — ${(_a = parsed.description) !== null && _a !== void 0 ? _a : 'unknown error'}`, { response: parsed });
+                        return;
+                    }
+                    resolve(parsed);
+                });
+            });
+            req.on('error', (e) => settle(`SmartAlert-T: transport error — ${e.message}`));
+            req.on('timeout', () => {
+                req.destroy();
+                settle('SmartAlert-T: request timed out.');
+            });
+            req.write(body);
+            req.end();
+        });
+    }
+}
+exports.SmartAlert = SmartAlert;
+SmartAlert.VERSION = '1.0.0';
+SmartAlert.API_BASE = 'https://api.telegram.org';

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "smart-alert-t",
+  "version": "1.0.0",
+  "description": "SmartAlert-T (SAT) — A lightweight Telegram alerting library for Node.js. The first line of defense for your servers and applications. Send critical, warning and info alerts to Telegram users or groups from cron jobs and background processes.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "commonjs",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "node test/smartAlert.test.js",
+    "example": "node examples/basic-usage.js"
+  },
+  "keywords": [
+    "telegram",
+    "alert",
+    "alerting",
+    "notification",
+    "monitoring",
+    "cron",
+    "bot",
+    "smartalert",
+    "sat",
+    "devops"
+  ],
+  "author": {
+    "name": "Gift Balogun",
+    "url": "https://giftbalogun.name.ng/"
+  },
+  "homepage": "https://giftbalogun.name.ng/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/giftbalogun/smart-alert-t.git"
+  },
+  "bugs": {
+    "url": "https://github.com/giftbalogun/smart-alert-t/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.41",
+    "typescript": "^5.4.0"
+  }
+}