mongo-alert-bot

TypeScript library and CLI that watches one or more MongoDB collections for new inserts and sends each document (JSON) to a Telegram chat via the Bot API.

Requirements

• Node.js 18+
• Telegram bot token from @BotFather
• Chat id for your bot (e.g. send a message to the bot, then open https://api.telegram.org/bot<TOKEN>/getUpdates and read message.chat.id)

Install

npm install mongo-alert-bot

Build from source:

npm install
npm run build

CLI

Environment variables (optional if you pass flags):

| Variable | Description | |----------|-------------| | MONGODB_URI | MongoDB connection string | | MONGODB_DB | Database name | | MONGODB_COLLECTION | One collection name, or comma-separated names (events,orders) | | TELEGRAM_BOT_TOKEN | Bot token | | TELEGRAM_CHAT_ID | Destination chat id |

Collections: repeat --collection and/or use commas: --collection events,orders or --collection events --collection orders. Duplicates are removed.

Change streams (default): needs a replica set (MongoDB Atlas or a local replica set). Standalone mongod does not support change streams.

npx mongo-alert-bot \
  --uri "mongodb://localhost:27017/?replicaSet=rs0" \
  --db mydb \
  --collection events \
  --telegram-token "$TELEGRAM_BOT_TOKEN" \
  --telegram-chat-id "$TELEGRAM_CHAT_ID"

Watch multiple collections:

npx mongo-alert-bot \
  --uri "mongodb://localhost:27017/?replicaSet=rs0" \
  --db mydb \
  --collection events --collection orders \
  --telegram-token "$TELEGRAM_BOT_TOKEN" \
  --telegram-chat-id "$TELEGRAM_CHAT_ID"

Polling (--poll): works on standalone MongoDB; polls every --poll-interval-ms (default 2000). Only documents strictly after the process starts are notified (baseline uses max existing _id or “now”), unless you use --resume-file to continue a cursor.

npx mongo-alert-bot --poll \
  --uri "mongodb://127.0.0.1:27017" \
  --db mydb \
  --collection events \
  --telegram-token "$TELEGRAM_BOT_TOKEN" \
  --telegram-chat-id "$TELEGRAM_CHAT_ID" \
  --resume-file ./poll.resume.json

With multiple collections, --resume-file ./data/poll.resume.json creates sibling files such as ./data/poll.events.resume.json and ./data/poll.orders.resume.json (collection names sanitized for the filesystem).

Tail by a timestamp field instead of _id:

npx mongo-alert-bot --poll \
  --timestamp-field createdAt \
  ...same other flags...

Optional custom message (placeholders: {db}, {collection}, {document}):

npx mongo-alert-bot ... \
  --message-template "Alert {db}.{collection}:\n{document}"

Stop with Ctrl+C (SIGINT) or SIGTERM.

Programmatic API

import { runWatcher } from "mongo-alert-bot";

const { close, done } = await runWatcher({
  mongoUri: process.env.MONGODB_URI!,
  dbName: "mydb",
  collectionNames: ["events", "orders"],
  telegramToken: process.env.TELEGRAM_BOT_TOKEN!,
  telegramChatId: process.env.TELEGRAM_CHAT_ID!,
  usePoll: true,
  pollIntervalMs: 3000,
});

done.catch(console.error);

process.on("SIGINT", () => {
  void close();
});

You can still pass a single name via collectionName: "events" or "events,orders" (comma-separated).

Security

Never commit TELEGRAM_BOT_TOKEN, database URIs with credentials, or .env. Prefer environment variables in production.

Manual smoke test

1. Run npm run build.
2. Start MongoDB (standalone is fine for --poll).
3. Run the CLI with --poll and valid Telegram credentials pointing at one or more test collections.
4. Insert a document into a watched collection (e.g. mongosh: db.events.insertOne({ hello: "world" })).
5. Confirm the Telegram chat receives a message with the document JSON (and that {collection} matches the source collection).
6. Press Ctrl+C and confirm the process exits.