@zero-bot.net/tg-bot-api 1.3.0 → 1.5.0

package/src/telegram.d.ts

@@ -2688,6 +2688,16 @@ export interface TelegramBotOptions {
   filepath?: boolean;
   /** Set to true for forward-compatibility on unhandled rejections. */
   badRejection?: boolean;
+  /**
+   * Apply latency-oriented network tuning at construction (prefer IPv4 and
+   * shorten Node's IPv6 fallback window). Mutates process-global DNS settings.
+   */
+  ipv4First?: boolean;
+  /**
+   * Warm up the connection (DNS/TCP/TLS) with a `getMe()` call at startup so
+   * the first real request is not a cold start.
+   */
+  prewarm?: boolean;
 }
 
 /** Polling options. */
@@ -3170,6 +3180,14 @@ export default class TelegramBot extends EventEmitter {
 
   /** The types of message updates the library handles. */
   static messageTypes: string[];
+  /**
+   * Apply latency-oriented network tuning (prefer IPv4, shorten Node's IPv6
+   * fallback window). Mutates process-global settings — call once at startup.
+   */
+  static applyNetworkTuning(options?: {
+    ipv4First?: boolean;
+    autoSelectFamilyAttemptTimeout?: number;
+  }): { ipv4First: boolean; autoSelectFamilyAttemptTimeout: number };
 
   // --- Event Overloads --------------------------------------------------------
 
@@ -3362,6 +3380,11 @@ export default class TelegramBot extends EventEmitter {
 
   /** A simple method for testing your bot's authentication token. */
   getMe(form?: FormQueryOptions): Promise<User>;
+  /**
+   * Warm up the connection (DNS/TCP/TLS) with a lightweight `getMe()` call so
+   * the first real request is not a cold start. Resolves with the bot instance.
+   */
+  preheat(options?: { suppressErrors?: boolean }): Promise<this>;
 
   /** Log out from the cloud Bot API server. */
   logOut(form?: FormQueryOptions): Promise<boolean>;
@@ -4999,10 +5022,17 @@ export default class TelegramBot extends EventEmitter {
   answerGuestQuery(guestQueryId: string, text: string, form?: FormQueryOptions): Promise<boolean>;
 
   /**
-   * Remove multiple reactions from a message.
-   * @see https://core.telegram.org/bots/api#deletemessagereactions
+   * Remove up to 10000 recent reactions in a group or supergroup added by a
+   * given user or chat.
+   *
+   * Pass the user id positionally, or an options object with `user_id` and/or
+   * `actor_chat_id`.
+   * @see https://core.telegram.org/bots/api#deleteallmessagereactions
    */
-  deleteAllMessageReactions(chatId: number | string, messageId: number, form?: FormQueryOptions): Promise<boolean>;
+  deleteAllMessageReactions(
+    chatId: number | string,
+    userIdOrOptions?: number | string | FormQueryOptions,
+  ): Promise<boolean>;
 
   /**
    * Remove a reaction from a message.

package/src/telegram.js

@@ -1,23 +1,32 @@
-// shims
-require('array.prototype.findindex').shim(); // for Node.js v0.x
-
 const errors = require('./errors');
 const TelegramBotWebHook = require('./telegramWebHook');
 const TelegramBotPolling = require('./telegramPolling');
 const debug = require('debug')('@zero-bot.net/tg-bot-api');
 const EventEmitter = require('eventemitter3');
-const fileType = require('file-type');
+const { detectFileType, lookupMime } = require('./fileTypes');
+const { applyNetworkTuning } = require('./network');
 const requestBase = require('@zero-bot.net/request');
-const request = (options) => new Promise((resolve, reject) => {
-  requestBase(options, (err, response) => {
-    if (err) reject(err);
-    else resolve(response);
+const request = (options) => {
+  let underlying = null;
+  const promise = new Promise((resolve, reject) => {
+    underlying = requestBase(options, (err, response) => {
+      if (err) reject(err);
+      else resolve(response);
+    });
   });
-});
+  // Expose cancellation so polling (and any caller) can abort an in-flight
+  // request. Aborting surfaces through the callback as a rejection.
+  promise.cancel = (reason) => {
+    if (underlying && typeof underlying.abort === 'function') {
+      underlying.abort();
+    }
+    return reason;
+  };
+  return promise;
+};
 const streamedRequest = requestBase;
 const qs = require('querystring');
 const stream = require('stream');
-const mime = require('mime');
 const path = require('path');
 const URL = require('url');
 const fs = require('fs');
@@ -224,6 +233,13 @@ class TelegramBot extends EventEmitter {
    *  **if and only if** the Node.js version you're using terminates the
    *  process on unhandled rejections. This option is only for
    *  *forward-compatibility purposes*.
+   * @param {Boolean} [options.ipv4First=false] Apply latency-oriented network
+   *  tuning at construction: prefer IPv4 and shorten Node's IPv6 fallback
+   *  window. This mutates process-global DNS settings — see
+   *  {@link TelegramBot.applyNetworkTuning}.
+   * @param {Boolean} [options.prewarm=false] Eagerly open the DNS/TCP/TLS
+   *  connection with a lightweight `getMe()` call so the first real request is
+   *  not a cold start.
    * @see https://core.telegram.org/bots/api
    */
   constructor(token, options = {}) {
@@ -235,12 +251,17 @@ class TelegramBot extends EventEmitter {
     this.options.baseApiUrl = options.baseApiUrl || 'https://api.telegram.org';
     this.options.filepath = (typeof options.filepath === 'undefined') ? true : options.filepath;
     this.options.badRejection = (typeof options.badRejection === 'undefined') ? false : options.badRejection;
+    this.options.request = Object.assign({}, options.request);
     this._textRegexpCallbacks = [];
     this._replyListenerId = 0;
     this._replyListeners = [];
     this._polling = null;
     this._webHook = null;
 
+    if (options.ipv4First) {
+      applyNetworkTuning({ ipv4First: true });
+    }
+
     if (options.polling) {
       const autoStart = options.polling.autoStart;
       if (typeof autoStart === 'undefined' || autoStart === true) {
@@ -254,6 +275,23 @@ class TelegramBot extends EventEmitter {
         this.openWebHook();
       }
     }
+
+    if (options.prewarm) {
+      // Fire-and-forget; a failed warm-up must not break construction.
+      this.preheat();
+    }
+  }
+
+  /**
+   * Apply latency-oriented network tuning (prefer IPv4, shorten Node's IPv6
+   * fallback window). Mutates process-global settings — call once at startup.
+   *
+   * @param  {Object} [options] See {@link module:network.applyNetworkTuning}
+   * @return {Object} The applied settings
+   * @see https://nodejs.org/api/dns.html#dnssetdefaultresultorderorder
+   */
+  static applyNetworkTuning(options) {
+    return applyNetworkTuning(options);
   }
 
   /**
@@ -358,7 +396,13 @@ class TelegramBot extends EventEmitter {
       'link_preview_options',
     ];
     for (const field of jsonFields) {
-      if (obj.hasOwnProperty(field) && typeof obj[field] !== 'string') {
+      // Skip null/undefined: `stringify(null)` would produce the string "null" and
+      // corrupt sentinel values such as `photo: null` set by sendPhoto() when
+      // uploading a Buffer/Stream (Telegram would then treat it as a file_id).
+      if (obj.hasOwnProperty(field)
+        && obj[field] !== null
+        && obj[field] !== undefined
+        && typeof obj[field] !== 'string') {
         obj[field] = stringify(obj[field]);
       }
     }
@@ -398,13 +442,14 @@ class TelegramBot extends EventEmitter {
     options.resolveWithFullResponse = true;
     options.forever = true;
     debug('HTTP request: %j', options);
-    return request(options)
+    const raw = request(options);
+    const promise = raw
       .then(resp => {
         let data;
         try {
           data = resp.body = JSON.parse(resp.body);
-        } catch (err) {
-          throw new errors.ParseError(`Error parsing response: ${resp.body}`, resp);
+        } catch (parseError) {
+          throw new errors.ParseError(`Error parsing response: ${parseError.message}`, resp);
         }
 
         if (data.ok) {
@@ -417,6 +462,13 @@ class TelegramBot extends EventEmitter {
         if (error.response) throw error;
         throw new errors.FatalError(error);
       });
+
+    // Keep cancellation available on the promise chain returned to callers.
+    if (typeof raw.cancel === 'function') {
+      promise.cancel = (reason) => raw.cancel(reason);
+    }
+
+    return promise;
   }
 
   /**
@@ -457,7 +509,7 @@ class TelegramBot extends EventEmitter {
         filename = 'data';
       }
       if (!contentType) {
-        const filetype = fileType(data);
+        const filetype = detectFileType(data);
         if (filetype) {
           contentType = filetype.mime;
           const ext = filetype.ext;
@@ -483,7 +535,7 @@ class TelegramBot extends EventEmitter {
     }
 
     filename = filename || 'filename';
-    contentType = contentType || mime.lookup(filename);
+    contentType = contentType || lookupMime(filename);
     if (process.env.NTBA_FIX_350) {
       contentType = contentType || 'application/octet-stream';
     } else {
@@ -1057,6 +1109,34 @@ class TelegramBot extends EventEmitter {
     return this._request('getMe', { form });
   }
 
+  /**
+   * Warm up the connection so the first real request is not a cold start.
+   *
+   * Issues a lightweight `getMe()` call, which establishes DNS, the TCP socket
+   * and the TLS session and populates the keep-alive pool. Worth calling once
+   * at startup for webhook / broadcast bots.
+   *
+   * By default a failed warm-up is swallowed (emitting `preheat_error`) so it
+   * is always safe to `await` at startup.
+   *
+   * @param  {Object} [options]
+   * @param  {Boolean} [options.suppressErrors=true] Resolve instead of rejecting
+   *  when the warm-up request fails.
+   * @return {Promise<TelegramBot>} Resolves with the bot instance
+   * @see https://core.telegram.org/bots/api#getme
+   */
+  preheat({ suppressErrors = true } = {}) {
+    const warm = this.getMe();
+    if (!suppressErrors) {
+      return warm.then(() => this);
+    }
+    return warm.then(() => this).catch((error) => {
+      debug('preheat failed: %s', error.message);
+      this.emit('preheat_error', error);
+      return this;
+    });
+  }
+
   /**
    * This method log out your bot from the cloud Bot API server before launching the bot locally.
    * You must log out the bot before running it locally, otherwise there is no guarantee that the bot will receive updates.
@@ -1131,7 +1211,7 @@ class TelegramBot extends EventEmitter {
   forwardMessages(chatId, fromChatId, messageIds, form = {}) {
     form.chat_id = chatId;
     form.from_chat_id = fromChatId;
-    form.message_ids = messageIds;
+    form.message_ids = stringify(messageIds);
     return this._request('forwardMessages', { form });
   }
 
@@ -4022,14 +4102,15 @@ class TelegramBot extends EventEmitter {
    * Use this method to remove multiple reactions from a message.
    *
    * @param  {Number|String} chatId Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
-   * @param  {Number} messageId Unique identifier of the target message
-   * @param  {Object} [options] Additional Telegram query options
+   * @param  {Number|Object} [options] Identifier of the user whose reactions are removed, or an options object (`user_id`/`actor_chat_id`)
    * @return {Promise} True on success
-   * @see https://core.telegram.org/bots/api#deletemessagereactions
+   * @see https://core.telegram.org/bots/api#deleteallmessagereactions
    */
-  deleteAllMessageReactions(chatId, messageId, form = {}) {
+  deleteAllMessageReactions(chatId, options = {}) {
+    const form = (typeof options === 'number' || typeof options === 'string')
+      ? { user_id: options }
+      : options;
     form.chat_id = chatId;
-    form.message_id = messageId;
     return this._request('deleteAllMessageReactions', { form });
   }
 
@@ -4224,12 +4305,48 @@ class TelegramBot extends EventEmitter {
    * @return {Promise} On success, the edited Message object is returned
    * @see https://core.telegram.org/bots/api#editephemeralmessagemedia
    */
-  editEphemeralMessageMedia(chatId, ephemeralMessageId, media, form = {}, fileOptions = {}) {
+  editEphemeralMessageMedia(chatId, ephemeralMessageId, media, form = {}) {
     if (!chatId) return Promise.reject(new Error('chatId is required'));
     if (!ephemeralMessageId) return Promise.reject(new Error('ephemeralMessageId is required'));
+
+    const regexAttach = /attach:\/\/.+/;
+
+    if (typeof media.media === 'string' && regexAttach.test(media.media)) {
+      const opts = { qs: form };
+      opts.formData = {};
+
+      const payload = Object.assign({}, media);
+      delete payload.media;
+
+      try {
+        const attachName = String(0);
+        const [formData] = this._formatSendData(
+          attachName,
+          media.media.replace('attach://', ''),
+          media.fileOptions
+        );
+
+        if (formData) {
+          opts.formData[attachName] = formData[attachName];
+          payload.media = `attach://${attachName}`;
+        } else {
+          throw new errors.FatalError(`Failed to process the replacement action for your ${media.type}`);
+        }
+      } catch (ex) {
+        return Promise.reject(ex);
+      }
+
+      opts.qs.chat_id = chatId;
+      opts.qs.ephemeral_message_id = ephemeralMessageId;
+      opts.qs.media = stringify(payload);
+
+      return this._request('editEphemeralMessageMedia', opts);
+    }
+
     form.chat_id = chatId;
     form.ephemeral_message_id = ephemeralMessageId;
     form.media = stringify(media);
+
     return this._request('editEphemeralMessageMedia', { form });
   }
 

package/src/telegramPolling.js

@@ -23,6 +23,7 @@ class TelegramBotPolling {
     }
     this._lastUpdate = 0;
     this._lastRequest = null;
+    this._currentRequest = null;
     this._abort = false;
     this._pollingTimeout = null;
   }
@@ -60,11 +61,15 @@ class TelegramBotPolling {
       return Promise.resolve();
     }
     const lastRequest = this._lastRequest;
+    const currentRequest = this._currentRequest;
     this._lastRequest = null;
+    this._currentRequest = null;
     clearTimeout(this._pollingTimeout);
     if (options.cancel) {
       const reason = options.reason || 'Polling stop';
-      lastRequest.cancel(reason);
+      if (currentRequest && typeof currentRequest.cancel === 'function') {
+        currentRequest.cancel(reason);
+      }
       return Promise.resolve();
     }
     this._abort = true;
@@ -98,8 +103,9 @@ class TelegramBotPolling {
    * @private
    */
   _polling() {
-    this._lastRequest = this
-      ._getUpdates()
+    const currentRequest = this._getUpdates();
+    this._currentRequest = currentRequest;
+    this._lastRequest = currentRequest
       .then(updates => {
         this._lastUpdate = Date.now();
         debug('polling data %j', updates);

package/src/telegramWebHook.js

@@ -3,7 +3,9 @@ const debug = require('debug')('@zero-bot.net/tg-bot-api');
 const https = require('https');
 const http = require('http');
 const fs = require('fs');
-const bl = require('bl');
+
+/** Default maximum accepted webhook body size (10 MiB). */
+const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
 
 class TelegramBotWebHook {
   /**
@@ -18,11 +20,13 @@ class TelegramBotWebHook {
     this.options.port = this.options.port || 8443;
     this.options.https = this.options.https || {};
     this.options.healthEndpoint = this.options.healthEndpoint || '/healthz';
+    this.options.maxBodySize = this.options.maxBodySize || DEFAULT_MAX_BODY_SIZE;
     this._healthRegex = new RegExp(this.options.healthEndpoint);
     this._webServer = null;
     this._open = false;
     this._requestListener = this._requestListener.bind(this);
     this._parseBody = this._parseBody.bind(this);
+    this._collectBody = this._collectBody.bind(this);
 
     if (this.options.key && this.options.cert) {
       debug('HTTPS WebHook enabled (by key/cert)');
@@ -104,6 +108,40 @@ class TelegramBotWebHook {
     return this.bot.emit('webhook_error', error);
   }
 
+  /**
+   * Buffer an incoming request body, enforcing the configured size limit.
+   * @private
+   * @param  {http.IncomingMessage} req
+   * @param  {Function} callback `(error, body)`
+   */
+  _collectBody(req, callback) {
+    const chunks = [];
+    let size = 0;
+    let done = false;
+
+    const finish = (error, body) => {
+      if (done) return;
+      done = true;
+      callback(error, body);
+    };
+
+    req.on('data', (chunk) => {
+      if (done) return undefined;
+      size += chunk.length;
+      if (size > this.options.maxBodySize) {
+        // Stop reading; the request listener answers with 413.
+        req.pause();
+        return finish(new errors.FatalError('WebHook request body exceeds maxBodySize'));
+      }
+      chunks.push(chunk);
+      return undefined;
+    });
+
+    req.on('end', () => finish(null, Buffer.concat(chunks)));
+    req.on('error', (error) => finish(error));
+    return undefined;
+  }
+
   /**
    * Handle request body by passing it to 'callback'
    * @private
@@ -139,9 +177,20 @@ class TelegramBotWebHook {
         res.statusCode = 418; // I'm a teabot!
         res.end();
       } else {
-        req
-          .pipe(bl(this._parseBody))
-          .on('finish', () => res.end('OK'));
+        this._collectBody(req, (error, body) => {
+          if (res.writableEnded) return undefined;
+          if (error) {
+            const tooLarge = /maxBodySize/.test(error.message);
+            debug('WebHook body rejected: %s', error.message);
+            res.statusCode = tooLarge ? 413 : 400;
+            res.setHeader('Connection', 'close');
+            res.end(tooLarge ? 'Payload Too Large' : 'Bad Request');
+            return undefined;
+          }
+          this._parseBody(null, body);
+          res.end('OK');
+          return undefined;
+        });
       }
     } else if (this._healthRegex.test(req.url)) {
       debug('WebHook health check passed');

package/.github/ISSUE_TEMPLATE.md

@@ -1,68 +0,0 @@
-<!--
-This template includes three sections:
-1. Bug reporting
-2. Feature request
-3. Question
-
-Please remove sections that do not apply to your issue
--->
-
-
-
-<!--********************************************************************
-Reporting a Bug.
-*********************************************************************-->
-
-> Bug Report
-
-I have read:
-
-* [Usage information](https://github.com/ZeroBot-net/tg-bot-api/tree/master/doc/usage.md)
-* [Help information](https://github.com/ZeroBot-net/tg-bot-api/tree/master/doc/help.md)
-
-I am using the latest version of the library.
-
-### Expected Behavior
-
-<!-- Explain what you are trying to achieve -->
-
-### Actual Behavior
-
-<!-- Explain what happens, contrary to what you expected -->
-
-### Steps to reproduce the Behavior
-
-<!-- Explain how we can reproduce the bug -->
-
-
-
-<!--********************************************************************
-Feature Request.
-*********************************************************************-->
-
-> Feature Request
-
-I have:
-
-* searched for such a feature request (https://github.com/ZeroBot-net/tg-bot-api/labels/enhancement) and found none
-
-### Introduction
-
-<!-- Describe what value this feature would add, and in which use case,
-or scenario -->
-
-### Example
-
-<!-- A code snippet of how this feature would work, were it already
-implemented -->
-
-
-
-<!--********************************************************************
-Question.
-*********************************************************************-->
-
-> Question
-
-<!-- Ask your question here. Please be precise, adding as much detail
-as necessary. Also, add a code snippet(s) if possible. -->

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -1,23 +0,0 @@
-<!--
-Mark whichever option below applies to this PR.
-For example, if your PR passes all tests, you would mark the option as so:
-- [x] All tests pass
-Note the 'x' in between the square brackets '[]'
--->
-- [ ] All tests pass
-- [ ] I have run `npm run doc`
-
-### Description
-
-<!-- Explain what you are trying to achieve with this PR -->
-
-### References
-
-<!--
-Add references to other documents/pages that are relevant to this
-PR, such as related issues, documentation, etc.
-
-For example,
-* Issue #1: https://github.com/ZeroBot-net/tg-bot-api/issues/1
-* Telegram Bot API - Getting updates: https://core.telegram.org/bots/api#getting-updates
--->