@overpod/mcp-telegram 1.34.0 → 1.35.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.35.0] — 2026-04-25
+
+### Changed
+
+**Rate limiter — structured stderr events for retries.**
+
+The internal `RateLimiter` previously logged `FLOOD_WAIT` and network retries as
+human-readable strings via `console.error`, and the temporary-server-error
+branch (5xx, etc.) was silent. All three retry branches now emit a single
+structured stderr line per event:
+
+```
+[rate-limiter] event {"event":"flood_wait","context":"list-chats","seconds":30,"attempt":1,"maxRetries":3}
+```
+
+Event types: `flood_wait`, `network_retry`, `temporary_retry`. Each event
+carries:
+
+- `event` — event class (string literal)
+- `context` — caller-supplied operation name (never user input / PII)
+- `attempt` / `maxRetries` — retry counters
+- `seconds` (flood_wait only) or `delayMs` (network/temporary)
+- `error` (network/temporary only) — the upstream Telegram error message
+
+This is a logging contract change, not a behaviour change: retry timing,
+backoff, and error-throwing semantics are identical to 1.34.0.
+
+### Why this matters
+
+Downstream log collectors can now aggregate retry rates by event class and
+caller without parsing free-form English. `mcp-telegram-cloud` v1.12.0+ wires
+this into SigNoz directly. Self-hosters can `grep '\[rate-limiter\] event'` or
+pipe into any structured log pipeline.
+
+### Compatibility
+
+No breaking changes. No new dependencies. No new environment variables.
+Tests: 490/490 pass.
+
 ## [1.34.0] — 2026-04-24
 
 ### Added

package/dist/rate-limiter.d.ts

@@ -1,6 +1,10 @@
 /**
  * Rate limiter and retry logic for Telegram API calls.
  * Handles FLOOD_WAIT errors and implements exponential backoff.
+ *
+ * Emits structured events on stderr so downstream log collectors (e.g. cloud
+ * SigNoz) can aggregate by `event` and `context`. Format:
+ *   [rate-limiter] event {"event":"flood_wait","context":"X","seconds":N,...}
  */
 export interface RateLimiterOptions {
     /** Maximum number of requests per second (default: 20) */

package/dist/rate-limiter.js

@@ -1,6 +1,10 @@
 /**
  * Rate limiter and retry logic for Telegram API calls.
  * Handles FLOOD_WAIT errors and implements exponential backoff.
+ *
+ * Emits structured events on stderr so downstream log collectors (e.g. cloud
+ * SigNoz) can aggregate by `event` and `context`. Format:
+ *   [rate-limiter] event {"event":"flood_wait","context":"X","seconds":N,...}
  */
 export class RateLimiter {
     minInterval;
@@ -41,7 +45,13 @@ export class RateLimiter {
                 if (attempt >= this.maxRetries) {
                     throw new Error(`Rate limit exceeded after ${this.maxRetries} retries. Telegram requires ${waitSeconds}s wait. Try again later.`);
                 }
-                console.error(`[rate-limiter] FLOOD_WAIT for ${context}. Waiting ${waitSeconds}s (attempt ${attempt + 1}/${this.maxRetries})`);
+                logEvent({
+                    event: "flood_wait",
+                    context,
+                    seconds: waitSeconds,
+                    attempt: attempt + 1,
+                    maxRetries: this.maxRetries,
+                });
                 await sleep(waitSeconds * 1000);
                 return this.executeWithRetry(fn, context, attempt + 1, options);
             }
@@ -51,7 +61,14 @@ export class RateLimiter {
                     throw new Error(`Network error after ${this.maxRetries} retries: ${errorMessage}. Check your connection.`);
                 }
                 const delay = Math.min(this.initialRetryDelay * 2 ** attempt, this.maxRetryDelay);
-                console.error(`[rate-limiter] Network error for ${context}. Retrying in ${delay}ms (attempt ${attempt + 1}/${this.maxRetries})`);
+                logEvent({
+                    event: "network_retry",
+                    context,
+                    delayMs: delay,
+                    attempt: attempt + 1,
+                    maxRetries: this.maxRetries,
+                    error: errorMessage,
+                });
                 await sleep(delay);
                 return this.executeWithRetry(fn, context, attempt + 1, options);
             }
@@ -61,6 +78,14 @@ export class RateLimiter {
                     throw new Error(`Temporary error after ${this.maxRetries} retries: ${errorMessage}`);
                 }
                 const delay = Math.min(this.initialRetryDelay * 2 ** attempt, this.maxRetryDelay);
+                logEvent({
+                    event: "temporary_retry",
+                    context,
+                    delayMs: delay,
+                    attempt: attempt + 1,
+                    maxRetries: this.maxRetries,
+                    error: errorMessage,
+                });
                 await sleep(delay);
                 return this.executeWithRetry(fn, context, attempt + 1, options);
             }
@@ -85,3 +110,6 @@ function isTemporaryError(msg) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function logEvent(payload) {
+    console.error(`[rate-limiter] event ${JSON.stringify(payload)}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
@@ -63,7 +63,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.12",
+    "@biomejs/biome": "^2.4.13",
     "@types/node": "^25.6.0",
     "@types/qrcode": "^1.5.6",
     "c8": "^11.0.0",