@patricktobias86/node-red-telegram-account 1.1.6 → 1.1.8

package/AGENTS.md

@@ -0,0 +1,4 @@
+# Repository Instructions
+
+- Always run `npm test` before creating a commit.
+- If a code change alters user-facing behavior, update the README and any relevant docs to reflect the change.

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.1.7] - 2025-07-22
+### Added
+- Mocha tests for the configuration node ensure sessions are reused correctly.
+
+### Changed
+- Session management now tracks active clients in a `Map` for safer reuse.
+
+## [1.1.8] - 2025-07-22
+### Fixed
+- Receiver and Command nodes now remove their event listeners when closed to prevent duplicate messages after redeploys.
+

package/README.md

@@ -10,13 +10,44 @@
 npm i @patricktobias86/node-red-telegram-account
 ```
 
-## Nodes
+This package contains a collection of Node‑RED nodes built on top of [GramJS](https://gram.js.org/). They make it easier to interact with the Telegram MTProto API from your flows.
 
-- resolve-userid – resolve a Telegram username to its numeric user ID
+## Node overview
+
+See [docs/NODES.md](docs/NODES.md) for a detailed description of every node. Below is a quick summary:
+
+- **config** – stores your API credentials and caches sessions for reuse.
+- **auth** – interactive login that outputs a `stringSession`.
+- **receiver** – emits messages for every incoming update (with optional ignore list). Event listeners are cleaned up on node close so redeploys won't duplicate messages.
+- **command** – triggers when an incoming message matches a command or regex. Event listeners are removed on redeploy to prevent duplicates.
+- **send-message** – sends text or media messages with rich options.
+- **send-files** – uploads one or more files with captions and buttons.
+- **get-entity** – resolves usernames, IDs or t.me links into Telegram entities.
+- **delete-message** – deletes one or more messages, optionally revoking them.
+- **iter-dialogs** – iterates over your dialogs (chats, groups, channels).
+- **iter-messages** – iterates over messages in a chat with filtering options.
+- **promote-admin** – promotes a user to admin with configurable rights.
+- **resolve-userid** – converts a username to a numeric user ID.
 
 ## Session management
 
-Connections to Telegram are cached by the configuration node. When the flow is
-redeployed, the existing session is reused instead of creating a new one.
-The client is only disconnected once no nodes reference that session anymore.
+Connections to Telegram are cached by the configuration node. A Map keyed by the `stringSession` tracks each client together with a reference count and the connection promise. If a node is created while another one is still connecting, it waits for that promise and then reuses the same client.
+
+A single `TelegramClient` instance is therefore shared between all flows that point to the same configuration node, even after a redeploy. When Node‑RED restarts it checks the cache and returns the existing client rather than creating a new connection. The reference count is decreased whenever a node using the session is closed. Once all nodes have closed and the count reaches zero, the cached client is disconnected.
+
+Example flows can be found in the [examples](examples) folder.
+
+## Running tests
+
+After cloning the repository, install dependencies and run the test suite with:
+
+```bash
+npm install
+npm test
+```
+
+The tests use Mocha and verify that sessions are properly cached across nodes.
+
+## Changelog
 
+See [CHANGELOG.md](CHANGELOG.md) for release notes.

package/docs/NODES.md

@@ -0,0 +1,22 @@
+# Node Overview
+
+The package provides a set of custom Node-RED nodes built around the [GramJS](https://gram.js.org/) library. Each node exposes a small part of the Telegram API, making it easier to build Telegram bots and automation flows.
+
+Below is a short description of each node. For a full list of configuration options see the built‑in help inside Node‑RED or open the corresponding HTML files in the `nodes/` directory.
+
+| Node | Description |
+|------|-------------|
+| **config** | Configuration node storing API credentials and connection options. Other nodes reference this to share a Telegram client and reuse the session. Connections are tracked in a Map with a reference count so multiple nodes can wait for the same connection. |
+| **auth** | Starts an interactive login flow. Produces a `stringSession` that can be reused with the `config` node. |
+| **receiver** | Emits an output message for every incoming Telegram message. Can ignore specific user IDs. Event handlers are automatically removed when the node is closed. |
+| **command** | Listens for new messages and triggers when a message matches a configured command or regular expression. The event listener is cleaned up on node close to avoid duplicates. |
+| **send-message** | Sends text messages or media files to a chat. Supports parse mode, buttons, scheduling, and more. |
+| **send-files** | Uploads one or more files to a chat with optional caption, thumbnails and other parameters. |
+| **get-entity** | Resolves a username, user ID or t.me URL into a Telegram entity object. |
+| **delete-message** | Deletes one or multiple messages from a chat. Can revoke messages for all participants. |
+| **iter-dialogs** | Iterates through the user’s dialogs (chats, groups, channels) and outputs the collected list. |
+| **iter-messages** | Iterates over messages in a chat with various filtering and pagination options. |
+| **promote-admin** | Grants admin rights to a user in a group or channel with configurable permissions. |
+| **resolve-userid** | Converts a Telegram username to its numeric user ID. |
+
+

package/nodes/command.js

@@ -9,44 +9,46 @@ module.exports = function (RED) {
     /** @type {TelegramClient} */
     const client =  this.config.client;
 
-    
-
-    try {
-      client.addEventHandler((update) => {
-        const message = update.message.message
+    const event = new NewMessage();
+    const handler = (update) => {
+        const message = update.message.message;
         if (message) {
             if (config.regex) {
                 const regex = new RegExp(config.command);
 
                 if (regex.test(message)) {
-                    
                     var msg = {
                         payload: {
                             update
                         }
                     };
-
-                    
                     node.send(msg);
                 }
             } else if (message === config.command) {
-                
                 var msg = {
                     payload: {
                         update
                     }
                 };
-
-                
                 node.send(msg);
             }
         }
-      }, new NewMessage());
-      
+    };
+
+    try {
+      client.addEventHandler(handler, event);
     } catch (err) {
       node.error('Authorization error: ' + err.message);
     }
 
+    this.on('close', () => {
+      try {
+        client.removeEventHandler(handler, event);
+      } catch (err) {
+        node.error('Handler removal error: ' + err.message);
+      }
+    });
+
   }
 
   RED.nodes.registerType('command', Command);

package/nodes/config.js

@@ -1,7 +1,7 @@
 const { TelegramClient } = require("telegram");
 const { StringSession } = require("telegram/sessions");
 
-const activeClients = {}; // Cache: session string → { client, refCount }
+const activeClients = new Map(); // Cache: session string → { client, refCount, connecting }
 
 module.exports = function (RED) {
     function TelegramClientConfig(config) {
@@ -16,12 +16,19 @@ module.exports = function (RED) {
 
         const node = this;
 
-        if (activeClients[sessionStr]) {
+        if (activeClients.has(sessionStr)) {
             // Reuse existing client
-            const record = activeClients[sessionStr];
+            const record = activeClients.get(sessionStr);
             this.client = record.client;
             record.refCount += 1;
-            node.status({ fill: "green", shape: "dot", text: "Reused existing client" });
+            if (record.connecting) {
+                node.status({ fill: "yellow", shape: "dot", text: "Waiting for connection" });
+                record.connecting.then(() => {
+                    node.status({ fill: "green", shape: "dot", text: "Reused existing client" });
+                }).catch(err => node.error("Connection error: " + err.message));
+            } else {
+                node.status({ fill: "green", shape: "dot", text: "Reused existing client" });
+            }
         } else {
             // Create and connect new client
             this.client = new TelegramClient(this.session, apiId, apiHash, {
@@ -30,24 +37,31 @@ module.exports = function (RED) {
                 requestRetries: config.requestRetries || 5,
             });
 
-            // Pre-store with refCount to ensure reuse during connection setup
-            activeClients[sessionStr] = { client: this.client, refCount: 1 };
+            node.status({ fill: "yellow", shape: "ring", text: "Connecting" });
 
-            this.client.connect().then(async () => {
-                const authorized = await this.client.isUserAuthorized();
-                if (!authorized) {
-                    node.error("Session is invalid");
-                } else {
+            const record = { client: this.client, refCount: 1, connecting: null };
+            record.connecting = this.client.connect()
+                .then(async () => {
+                    const authorized = await this.client.isUserAuthorized();
+                    if (!authorized) {
+                        throw new Error("Session is invalid");
+                    }
+                })
+                .then(() => {
                     node.status({ fill: "green", shape: "dot", text: "Connected" });
-                }
-            }).catch(err => {
-                node.error("Connection error: " + err.message);
-                delete activeClients[sessionStr];
-            });
+                    record.connecting = null;
+                })
+                .catch(err => {
+                    node.error("Connection error: " + err.message);
+                    activeClients.delete(sessionStr);
+                    record.connecting = null;
+                });
+
+            activeClients.set(sessionStr, record);
         }
 
         this.on("close", async () => {
-            const record = activeClients[sessionStr];
+            const record = activeClients.get(sessionStr);
             if (record && record.client === this.client) {
                 record.refCount -= 1;
                 if (record.refCount <= 0) {
@@ -56,7 +70,7 @@ module.exports = function (RED) {
                     } catch (err) {
                         node.error("Disconnect error: " + err.message);
                     }
-                    delete activeClients[sessionStr];
+                    activeClients.delete(sessionStr);
                     node.status({ fill: "red", shape: "ring", text: "Disconnected" });
                 }
             }

package/nodes/receiver.js

@@ -8,24 +8,31 @@ module.exports = function (RED) {
     const client =  this.config.client;
     const ignore = config.ignore.split(/\n/);
 
-  
-    try {
-      client.addEventHandler((update) => {
-        if(update.message.fromId != null && !ignore.includes(update.message.fromId.userId.toString())){
-          
-          node.send({
-            payload:{
-              update
-            }
-          } )
+    const event = new NewMessage();
+    const handler = (update) => {
+        if (update.message.fromId != null && !ignore.includes(update.message.fromId.userId.toString())) {
+            node.send({
+                payload: {
+                    update
+                }
+            });
         }
-        
-      }, new NewMessage());
-      
+    };
+
+    try {
+      client.addEventHandler(handler, event);
     } catch (err) {
       node.error('Authorization error: ' + err.message);
     }
 
+    this.on('close', () => {
+      try {
+        client.removeEventHandler(handler, event);
+      } catch (err) {
+        node.error('Handler removal error: ' + err.message);
+      }
+    });
+
   }
 
   RED.nodes.registerType('receiver', Receiver);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patricktobias86/node-red-telegram-account",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Node-RED nodes to communicate with GramJS.",
   "main": "nodes/config.js",
   "keywords": [
@@ -45,5 +45,12 @@
   },
   "dependencies": {
     "telegram": "^2.17.10"
+  },
+  "devDependencies": {
+    "mocha": "^11.7.1",
+    "proxyquire": "^2.1.3"
+  },
+  "scripts": {
+    "test": "mocha"
   }
 }

package/test/command.test.js

@@ -0,0 +1,43 @@
+const assert = require('assert');
+const proxyquire = require('proxyquire').noPreserveCache();
+
+function load() {
+  const addCalls = [];
+  const removeCalls = [];
+  class TelegramClientStub {
+    addEventHandler(fn, event) { addCalls.push({fn, event}); }
+    removeEventHandler(fn, event) { removeCalls.push({fn, event}); }
+  }
+  class NewMessageStub {}
+
+  let NodeCtor;
+  const configNode = { client: new TelegramClientStub() };
+  const RED = {
+    nodes: {
+      createNode(node) {
+        node._events = {};
+        node.on = (e, fn) => { node._events[e] = fn; };
+      },
+      registerType(name, ctor) { NodeCtor = ctor; },
+      getNode() { return configNode; }
+    }
+  };
+
+  proxyquire('../nodes/command.js', {
+    'telegram/events': { NewMessage: NewMessageStub }
+  })(RED);
+
+  return { NodeCtor, addCalls, removeCalls };
+}
+
+describe('Command node', function() {
+  it('removes event handler on close', function() {
+    const { NodeCtor, addCalls, removeCalls } = load();
+    const node = new NodeCtor({config:'c', command:'cmd', regex:false});
+    assert.strictEqual(addCalls.length, 1);
+    node._events.close();
+    assert.strictEqual(removeCalls.length, 1);
+    assert.strictEqual(removeCalls[0].fn, addCalls[0].fn);
+    assert.strictEqual(removeCalls[0].event, addCalls[0].event);
+  });
+});

package/test/config.test.js

@@ -0,0 +1,62 @@
+const assert = require('assert');
+const proxyquire = require('proxyquire').noPreserveCache();
+
+function load() {
+  const instances = [];
+  class TelegramClientStub {
+    constructor(session, id, hash, opts) {
+      this.session = session;
+      this.id = id;
+      this.hash = hash;
+      this.opts = opts;
+      instances.push(this);
+    }
+    connect() { return Promise.resolve(); }
+    isUserAuthorized() { return Promise.resolve(true); }
+    disconnect() { return Promise.resolve(); }
+  }
+  class StringSessionStub {
+    constructor(str) { this.str = str; }
+  }
+
+  let NodeCtor;
+  const RED = {
+    nodes: {
+      createNode(node) {
+        node._events = {};
+        node.on = (e, fn) => { node._events[e] = fn; };
+        node.status = () => {};
+      },
+      registerType(name, ctor) { NodeCtor = ctor; }
+    }
+  };
+
+  proxyquire('../nodes/config.js', {
+    telegram: { TelegramClient: TelegramClientStub },
+    'telegram/sessions': { StringSession: StringSessionStub }
+  })(RED);
+
+  return { NodeCtor, instances };
+}
+
+describe('TelegramClientConfig', function() {
+  it('creates only one client for identical sessions', async function() {
+    const { NodeCtor, instances } = load();
+    const cfg = { session: 'sess', api_id: 1, api_hash: 'hash' };
+    const a = new NodeCtor(cfg);
+    const b = new NodeCtor(cfg);
+    assert.strictEqual(instances.length, 1);
+    assert.strictEqual(a.client, b.client);
+  });
+
+  it('reuses session after node redeploy', async function() {
+    const { NodeCtor, instances } = load();
+    const cfg = { session: 'sess', api_id: 1, api_hash: 'hash' };
+    const a = new NodeCtor(cfg);
+    const b = new NodeCtor(cfg);
+    await a._events.close();
+    const c = new NodeCtor(cfg);
+    assert.strictEqual(instances.length, 1);
+    assert.strictEqual(b.client, c.client);
+  });
+});

package/test/receiver.test.js

@@ -0,0 +1,43 @@
+const assert = require('assert');
+const proxyquire = require('proxyquire').noPreserveCache();
+
+function load() {
+  const addCalls = [];
+  const removeCalls = [];
+  class TelegramClientStub {
+    addEventHandler(fn, event) { addCalls.push({fn, event}); }
+    removeEventHandler(fn, event) { removeCalls.push({fn, event}); }
+  }
+  class NewMessageStub {}
+
+  let NodeCtor;
+  const configNode = { client: new TelegramClientStub() };
+  const RED = {
+    nodes: {
+      createNode(node) {
+        node._events = {};
+        node.on = (e, fn) => { node._events[e] = fn; };
+      },
+      registerType(name, ctor) { NodeCtor = ctor; },
+      getNode() { return configNode; }
+    }
+  };
+
+  proxyquire('../nodes/receiver.js', {
+    'telegram/events': { NewMessage: NewMessageStub }
+  })(RED);
+
+  return { NodeCtor, addCalls, removeCalls };
+}
+
+describe('Receiver node', function() {
+  it('removes event handler on close', function() {
+    const { NodeCtor, addCalls, removeCalls } = load();
+    const node = new NodeCtor({config:'c', ignore:''});
+    assert.strictEqual(addCalls.length, 1);
+    node._events.close();
+    assert.strictEqual(removeCalls.length, 1);
+    assert.strictEqual(removeCalls[0].fn, addCalls[0].fn);
+    assert.strictEqual(removeCalls[0].event, addCalls[0].event);
+  });
+});