komandero-telegram-monitor

Monitor Telegram chats for specific file types from specific users via MTProto (personal account, not a bot).

Install

npm install komandero-telegram-monitor

Prerequisites

Get your API_ID and API_HASH from https://my.telegram.org/apps.

Usage

import { TelegramFileMonitor } from "komandero-telegram-monitor";

const monitor = new TelegramFileMonitor({
  apiId: 123456,
  apiHash: "your_api_hash",
  session: "",               // empty on first run, persist via onSessionUpdate
  targetUser: "username",    // username (without @) or numeric ID
  downloadDir: "./downloads",
  fileExtension: ".csv",
});

monitor.onSessionUpdate((session) => {
  // persist the session string however you want (DB, file, env, etc.)
  // this avoids re-authenticating on every restart
});

monitor.onFile(({ filePath, fileName, senderName, senderId, timestamp, error }) => {
  if (error) {
    console.error(`Download failed: ${error.message}`);
    return;
  }
  console.log(`${senderName} sent ${fileName} -> ${filePath}`);
});

await monitor.start();

API

new TelegramFileMonitor(options)

| Option | Type | Default | Description | |---|---|---|---| | apiId | number\|string | required | Telegram API ID | | apiHash | string | required | Telegram API Hash | | session | string | "" | StringSession from previous auth | | targetUser | string | undefined | Username or numeric ID to monitor | | downloadDir | string | "./downloads" | Where to save downloaded files | | fileExtension | string | ".csv" | File extension to filter | | connectionRetries | number | 5 | MTProto connection retries | | auth | object | interactive stdin | Override auth callbacks (see below) |

Custom auth

new TelegramFileMonitor({
  // ...
  auth: {
    phoneNumber: async () => "+1234567890",
    phoneCode: async () => "12345",
    password: async () => "my2faPassword",
    onError: (err) => console.error(err),
  },
});

monitor.onFile(callback) -> this

Register a callback for when a matching file is received. Payload:

{
  fileName: string;
  filePath: string | null;  // null on download error
  senderName: string | null;
  senderId: string;
  timestamp: Date;
  error: Error | null;
}

monitor.onSessionUpdate(callback) -> this

Register a callback when the session string changes (first auth or refresh).

monitor.start() -> Promise<this>

Connect and start listening.

monitor.stop() -> Promise<void>

Disconnect.

monitor.listChats(limit?) -> Promise<Array>

List recent chats. Returns { id, name, username }[]. Useful to find targetUser values.

monitor.client

Direct access to the underlying GramJS TelegramClient for advanced use.

License

ISC