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

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,11 @@
+# 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.
+

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).
+- **command** – triggers when an incoming message matches a command or regex.
+- **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. |
+| **command** | Listens for new messages and triggers when a message matches a configured command or regular expression. |
+| **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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patricktobias86/node-red-telegram-account",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "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/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);
+  });
+});